A Short Primer on HTTP Requests

HTTP requests are at the heart of any REST-ful API. Essentially, these are messages consisting of a so-called HTTP verb (i.e., the method to be executed on the remote web server), a set of headers containing meta data about the request, and optionally a request body. The response of the HTTP requests similarly consists of a set of headers and a body, and is generally stateless, i.e., it only depends on the nature of the request but not on the state of the server when the request was received.

Abstract notation

We often use the a schematic notation or “pseudo code” to specify requests, similar to the following example:

GET https://gorest.co.in/public/v2/todos?status=pending&user_id=3221

GET is the HTTP verb to retrieve data from the server, followed by the URL of the desired resource (i.e., the server address). This exemplary request lists all to-dos in a database.

New data is added to the database with the POST verb:

POST https://gorest.co.in/public/v2/todos
content-type: application/json

{
    "title": "Clean kitchen"
}

The header content-type tells the server to interpret the string in the body as an object in JSON. A comprehensive list of headers can be found here. The semantics of all allowed HTTP verbs is explained here.

Query parameters

The part of the URL following the quotation mark in above GET request passes additional data to limit the query result. A series of key-value pairs is separated by the & character. Using the syntax from the qs package, we can also pass nested objects or arrays in the query string. For example, status=pending&user[name]=foo is interpreted as

{
    "status" "pending",
    "user": {
        "name": "foo"
    }
}

or a[]=b&a[]=c as

{
    "a": ["b", "c"]
}

Note that a URL may only contain ASCII characters and any violating (i.e., UTF8-encoded) parts must be escaped properly, e.g., with the function encodeURIComponent().

Requests in Python

Even though Python has built-in support for HTTP, most applications rely on the requests module. With that, the schematic request from above is easily implemented as follows:

import requests

http_request = requests.post(
    'https://gorest.co.in/public/v2/todos',
    headers={'content-type': 'application/json'},
    data={
        'title': 'Clean kitchen'
    })

reponse = http_request.json()

Note that if the response body is of type application/json (which can be verified by inspecting the response header content-type), it can be parsed into a Python dictionary by calling .json() on the object returned from the post function.

Requests in JavaScript

JavaScript code executed in the browser can leverage on the build-int Fetch API to make above POST request:

fetch('https://gorest.co.in/public/v2/todos',
{
  method: 'POST',
  headers: {
    content_type: 'application/json'
  },
  body: {
    title: 'Clean kitchen'
  }
})
.then(function(response) {
    return response.json();
}).then(function(body) {
    console.log(body);
});

cURL

cURL is a tool for transferring data on the command line with full support of the HTTP protocol. Above POST request, for example, is issued like so:

curl -X POST https://gorest.co.in/public/v2/todos -H 'Content-Type: application/json' -d '{"title":"Clean kitchen"}'

Note how the verb, headers, and data are passed with the -X, -H, and -d flags respectively.