API

SimpleJsonApiClient

Simple example

from tna_utilities.api import SimpleJsonApiClient

# Create an API client with a base URL
client = SimpleJsonApiClient("https://wagtail.nationalarchives.gov.uk/api/v2")

# Get the data from the /pages/ endpoint
pages = client.get("pages")

# Get the data from the /global-notifications/ endpoint
global_notifications = client.get("global-notifications")

Handling errors

from tna_utilities.api import SimpleJsonApiClient

client = SimpleJsonApiClient("https://wagtail.nationalarchives.gov.uk/api/v2")

try:
    pages = client.get("pages")
except Exception as error:
    print(f"An error occurred with the API: {error}")
    pages = []

You can catch and handle some of the more common exceptions:

• tna_utilities.api.ResourceForbidden
• tna_utilities.api.ResourceNotFound
• tna_utilities.api.ResourceUnauthorized

You can also catch exceptions raised by requests.

from requests import Timeout
from tna_utilities.api import SimpleJsonApiClient

client = SimpleJsonApiClient("https://wagtail.nationalarchives.gov.uk/api/v2")

try:
    pages = client.get("pages")
except Timeout:
    print("The request timed out")
    pages = []

Headers

from tna_utilities.api import SimpleJsonApiClient

# Set a default header for any request from the client
client = SimpleJsonApiClient(
    "https://wagtail.nationalarchives.gov.uk/api/v2",
    default_headers={
        "Host": "my.test.client.com"
    }
)

# Append a default header to all requests
client.add_default_header("Authorization", "Token abc123")

# Add a specific header to the GET request
#   Host: my.test.client.com
#   Authorization: Token abc123
#   Pragma: no-cache
pages = client.get(
    "pages",
    headers={
        "Pragma": "no-cache"
    }
)

#   Host: my.test.client.com
#   Authorization: Token abc123
global_notifications = client.get("global-notifications")

Query parameters

from tna_utilities.api import SimpleJsonApiClient

# Append a default query parameter to all requests
client = SimpleJsonApiClient(
    "https://wagtail.nationalarchives.gov.uk/api/v2",
    default_params={
        "format": "json"
    }
)

# Append a default query parameter to all requests
client.add_default_parameter("limit", "100")

# https://wagtail.nationalarchives.gov.uk/api/v2/pages/?format=json&limit=100&offset=400
pages = client.get(
    "pages",
    params={
        "offset": "400"
    }
)