HTTP - REST API - Cheatsheet

HTTP (short for Hyper Text Transfer Protocol) may very well be the backbone of the internet. So much of the internet’s traffic relies on this simple protocol is astonishing. Use-cases range from simple static websites to awfully complicated single-page apps and lots of things in between. I will be providing you with a minimal introduction to HTTP, just enough to get you started. There is too much to fully HTTP in one article, so I will be focusing on relevant concepts used for a REST API.

Table of Contents

Protocol overview

Under the hood, HTTP follows the classic request-response pattern. The client (generally, a web browser) sends the request and the server responds with the appropriate information. I’m aware that I am omitting server-side push and long-lived connections, but the model I’m providing should suffice for now.

The request:

POST /posts  HTTP/1.1

Content-Type: application/json
User-Agent: PostmanRuntime/7.21.0
Accept: */*
Cache-Control: no-cache
Host: jsonplaceholder.typicode.com
Accept-Encoding: gzip, deflate
Content-Length: 64
Connection: keep-alive 

{
      "title": "foo",
      "body": "bar",
      "userId": 1
}

Legend

Method
Relative Path (Relative URL)
Protocol / Version
Headers
Body

The response:

HTTP/1.1 201 Created

Date: Wed, 25 Dec 2019 19:08:15 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 65
Connection: keep-alive
X-Powered-By: Express
Vary: Origin, X-HTTP-Method-Override, Accept-Encoding
Access-Control-Allow-Credentials: true
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Access-Control-Expose-Headers: Location
Location: http://jsonplaceholder.typicode.com/posts/101
X-Content-Type-Options: nosniff
Etag: W/"41-GDNaWfnVU6RZhpLbye0veBaqcHA"
Via: 1.1 vegur
CF-Cache-Status: DYNAMIC
Server: cloudflare
CF-RAY: 54ad1a3ebcb5ce73-LHR

{
  "title": "foo",
  "body": "bar",
  "userId": 1,
  "id": 101
}

Legend

Protocol
Status Code
Headers
Body

Body

The body for the request or response can use many formats. We don’t have enough time to go through all available formats here, so we’re just going to focus on the most relevant formats when building a REST API.

JSON (Javascript Object Notation) – it was first used as a way to transport Javascript objects over the network. In the meantime, it has evolved into the main method of transporting data (machine to machine) over the internet.

Sample data:

{ 
   "intField":10,
   "stringField":"value",
   "arrayField":[ 
      1,
      2,
      3
   ],
   "complexField":{ 
      "intField":12,
      "stringField":"value"
   }
}

}

The main advantages of JSON are:

Shorter: You only need to pass the data you need and you use. This means less data over the wire which means a lot of time saved over the long run
No predefined schema: JSON does not impose any limitations the way the data is structured (as long as it’s a valid JSON, of course). This can be both an advantage, allowing you to only send the data you need and removing the need to maintain a data schema separately, and a curse, since you have no way of knowing ahead of time, what is the structure of the data you are going to receive.

XML (Extensible Markup Language) – it started off as a way address o the fact that the HTML tags are predefined (which is one of the main drawbacks for HTML). Please keep in mind that XML and HTML serve different purposes. HTML is designed hold data that is to be presented to the user (in one way or another), while XML is designed to hold data that is to be interpreted by a machine (although it’s fairly easy to make sense of the data as a human)

Sample data:

<request>
    <intField>1</intField>
    <stringField>some value</stringField>
    <complexField>
        <intField>2</intField>
        <emptyField attribute="1" />
        <intFieldWithAttribute attribute="foo">
            3
        </intFieldWithAttribute>
    </complexField>
</request>

XML also allows for a Document Type Definition (DTD) to be part of the data. Within the DTD, you can define what tags are allowed and what types of values are allowed for each of the fields. You have a real-life example of a DTD here.

A complete example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE note SYSTEM "Note.dtd">
<note>
    <to>Tove</to>
    <from>Jani</from>
    <heading>Reminder</heading>
    <body>Don't forget me this weekend!</body>
</note>

Note.dtd

<!DOCTYPE note
[
<!ELEMENT note (to,from,heading,body)>
<!ELEMENT to (#PCDATA)>
<!ELEMENT from (#PCDATA)>
<!ELEMENT heading (#PCDATA)>
<!ELEMENT body (#PCDATA)>
]>

Source here

Methods

Here is a list of the most commonly used HTTP methods. Keep in mind that the behavior I’m describing is best-practice, and there is very little standing in your way if you want to build your API to treat these methods differently.

GET – is used to fetch resources from the server. The method should not have a request body. All the data you need to send to the server should be sent either by query parameters, headers or cookies. The GET method should not change the state of the server. In other words, GET should result in read-only operations.
POST – is used to pass data to the server. As of HTTP 1.1, the data can be passed using any format. In terms of responsibilities, the POST method is used either as a result of a form submission or when you need to append a resource to a list on the server, or both (append a resource to a list on the server as a result of a form submission).
PUT – either creates a resource on the server or updates the resource if it already exists. The difference between POST and PUT is that PUT should be idempotent (as in, you can send the same request one time, or multiple times, and the result is the same)
PATCH – is used to partially update a resource. The difference between PUT and PATCH is that PUT is used to fully replace the resource, whereas PATCH is used to update (partially or totally) the resource in question. Please note that PATCH is not idempotent. This means that multiple identical PATCH request can have side effects. Of course, you have the option to build your API to treat PATCH requests idempotently.
DELETE – is used to remove a resource from the server.
OPTIONS – is what is called a pre-flight request. When the browser is about to send a request to a server that is hosted on a different domain (with some exceptions), it sends a OPTIONS request first to ask for information about the URL. The main components of the response are the following headers:

– Access-Control-Allow-Methods – Which contains a list of methods that are accepted by the URL

– Access-Control-Allow-Origin – Which contains a list of origins that are allowed to access the URL. This header is used by the browser to prevent Cross-Site Scripting (XSS) attacks

Just to get something clear, there is a lot to unpack about pre-flight request and Cross Origin Resource Sharing (CORS). I’m barely scratching the surface here.

Status Codes

1xx – Informational status codes.

100 Continue – Everything is ok so far, carry on.
101 Switching protocols – The server agrees to change protocols as per the Upgrade header passed in the request

2xx – Success

200 OK – The server accepts the request and responds with data. This is the usual response for GET requests
201 Created – The server accepted the request and created the appropriate resource. This is usually a response for POST or PUT requests.
204 No Content – The server accepted the request and fulfilled it, but there is no data to return.

3xx – Redirect

301 Permanently moved – The resource you are requesting has been permanently moved to a different location. Pay attention when using this status as browsers will cache the new URL forever. On the other side, this kind of status code is really useful if you plan to change your domain as search engines will take note of that and carry over your domain authority to the new URL.
302 Found – The resource you are requesting has been temporarily moved to a new location. If you are using this status, then the search engines will not carry over your domain authority to the new URL
304 Not Modified – There is no need to respond to the request as the data has not changed and the browser can just serve the cached version instead. This is used in conjunction with the If-Modified-Since header on the request.

4xx – Client error

400 Bad Request – The request sent by the client does not match the server expectations. The server refuses to process the request. It’s most commonly caused by a malformed request.
401 Unauthorized – The request requires some form of authorization that was not provided in order to access the resource.
403 Forbidden – The server refuses to serve your request. This is different from Unauthorized in meaning. With Forbidden, the server understood the request and is refusing to fulfill it. The request may contain valid authorization, but the resource is not accessible with the provided credentials.
404 Not Found – This is probably the most common error response out there. It occurs when the requested resource cannot be found.
405 Method Not Allowed – The provided method cannot be used to access the requested URL. This response usually contains an Allow header, that contains the list of allowed methods.

5xx – Server error

500 Internal Server error – This is a generic server error. Something went wrong and the server is unable to fulfill the request.
502 Bad Gateway – The server, while working as a proxy failed to fulfill the request. Generally, this means that a call from the backend to a third party service(such as the database) failed.
503 Service Unavailable – This is bad. The server is down and is unable to handle requests at this time.

HTTP – REST API – Cheatsheet