Constructing a REST API Request

What it is

A REST API request is an HTTP message that asks a server to read or change a resource.

REST treats everything as a resource with its own address. You act on a resource by sending a method such as GET or POST to that address.

To build a correct request from documentation, you pick the method, build the address, add headers and, when needed, add a body.

How it works

Every request has the same four parts, and the documentation tells you the value for each.

Parts of a URL

A URL has several parts.

Path parts that identify one item, such as the device ID 42 above, are called path parameters. Query parameters filter or page a list and are joined with an ampersand sign.

HTTP methods and CRUD

GET and DELETE normally have no body. POST, PUT and PATCH usually carry a body that describes the data.

A method is safe if it only reads, which is true of GET. A method is idempotent if repeating it gives the same final result. GET, PUT and DELETE are idempotent, but POST is not, because each call can create another resource.

Headers

Headers carry details about the request.

• Authorization holds credentials, as covered on the authentication page.
• Content-Type states the format of the body that you send.
• Accept states the format that you want back.

Reading the documentation

API documentation lists each operation with its method, path, parameters and an example. Suppose it says this for creating a space in a messaging service:

POST /v1/rooms
Header: Authorization: Bearer ACCESS_TOKEN
Header: Content-Type: application/json
Body field: title (string, required)
Response: 200 with the new room as JSON

You turn that into a raw HTTP request.

POST /v1/rooms HTTP/1.1
Host: api.example.test
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{"title": "Network Ops"}

The first line holds the method, the path and the HTTP version. The Host header names the server. A blank line separates the headers from the body.

The same request in Python

import requests

url = BASE_URL + "/v1/rooms"
headers = {
    "Authorization": "Bearer ACCESS_TOKEN",
    "Content-Type": "application/json",
}
payload = {"title": "Network Ops"}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())

Here BASE_URL stands for the scheme and host given in the documentation. The json= argument converts the dictionary to JSON for you.

A GET with query parameters

params = {"limit": 10, "type": "group"}
response = requests.get(BASE_URL + "/v1/rooms", headers=headers, params=params)

The library builds the query string from the dictionary. The path ends up as /v1/rooms?limit=10&type=group.

Checking your request against the documentation

• The method matches the action, for example POST to create.
• The path is complete, and every path parameter is filled in.
• Required headers and body fields are present.
• The body is valid JSON and the Content-Type says so.