Calling a REST API with the Requests Library

What it is

The requests library is the standard third party Python package for sending HTTP requests.

It turns the parts of a request into function arguments and the parts of a response into attributes. A few lines of code replace a lot of low level work.

You install it with pip install requests, then import it in your script.

How it works

You call a function named after the method, then read the Response object that it returns.

The basic functions

Useful arguments

The Response object

A complete script

This script lists devices from a fictional API, with an API key held in an environment variable.

import os
import requests

BASE_URL = os.environ["API_BASE"]
API_KEY = os.environ["API_KEY"]

headers = {
    "Authorization": "Bearer " + API_KEY,
    "Accept": "application/json",
}
params = {"limit": 20}

try:
    response = requests.get(
        BASE_URL + "/v1/devices",
        headers=headers,
        params=params,
        timeout=10,
    )
    response.raise_for_status()
except requests.exceptions.RequestException as err:
    print("Request failed:", err)
else:
    for device in response.json()["items"]:
        print(device["name"], device["status"])

The try block catches network problems and bad status codes. The else block runs only when the call worked.

Creating a resource with POST

payload = {"name": "edge-sw1", "site": "London"}

response = requests.post(
    BASE_URL + "/v1/devices",
    headers=headers,
    json=payload,
    timeout=10,
)
print(response.status_code)
print(response.json())

Because json=payload is used, there is no need to call json.dumps() yourself.

Updating and deleting

requests.put(BASE_URL + "/v1/devices/42", headers=headers, json=payload)
requests.delete(BASE_URL + "/v1/devices/42", headers=headers)

A successful DELETE often returns 204 with no body, so do not call .json() on it.

Sessions

A requests.Session object keeps settings and the connection across calls. This saves repeating the same headers.

session = requests.Session()
session.headers.update(headers)

devices = session.get(BASE_URL + "/v1/devices", timeout=10)
sites = session.get(BASE_URL + "/v1/sites", timeout=10)

Certificates and the verify argument

By default, requests checks the server certificate. Lab devices often use self signed certificates, which makes the call fail.

Setting verify=False turns the check off and works in a lab. It removes protection against impostors, so avoid it in production. A better fix is to point verify at the right certificate file.

Common error types

• requests.exceptions.ConnectionError when the server cannot be reached.
• requests.exceptions.Timeout when the server did not answer in time.
• requests.exceptions.HTTPError when raise_for_status() sees a 4xx or 5xx code.