Enhance SimpleJsonApiClient documentation and error handling; add examples for usage, headers, and query parameters

ahosgood · ahosgood · commit f7df3ed50ac1 · 2026-04-14T16:46:26.000+01:00
diff --git a/docs/api.md b/docs/api.md
@@ -2,4 +2,94 @@
 
 ## `SimpleJsonApiClient`
 
-TODO
+### Simple example
+
+```python
+from tna_utilities.flask.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
+
+```python
+from tna_utilities.flask.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 occured with the API: {error}")
+    pages = []
+```
+
+You can catch and handle some of the more common exceptions:
+
+- `tna_utilities.flask.api.ResourceForbidden`
+- `tna_utilities.flask.api.ResourceNotFound`
+- `tna_utilities.flask.api.ResourceUnauthorized`
+
+### Headers
+
+```python
+from tna_utilities.flask.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_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
+
+```python
+from tna_utilities.flask.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_parameter("limit", "100")
+
+# https://wagtail.nationalarchives.gov.uk/api/v2/pages/?format=json&limit=100&offset=400
+pages = client.get(
+    "pages",
+    params={
+        "offset": "400"
+    }
+)
+```
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -1,7 +1,13 @@
 import json
 from unittest import TestCase, mock
 
-from tna_utilities.api import ResourceForbidden, ResourceNotFound, SimpleJsonApiClient
+from requests import Timeout
+from tna_utilities.api import (
+    ResourceForbidden,
+    ResourceNotFound,
+    ResourceUnauthorized,
+    SimpleJsonApiClient,
+)
 
 MOCK_API_BASE_URL = "http://mockapi.com/"
 
@@ -22,10 +28,14 @@ def json(self):
         return MockResponse({"foo": "bar"}, 200)
     elif args[0] == f"{MOCK_API_BASE_URL}badrequest":
         return MockResponse(None, 400)
+    elif args[0] == f"{MOCK_API_BASE_URL}unauthorized":
+        return MockResponse(None, 401)
     elif args[0] == f"{MOCK_API_BASE_URL}forbidden":
         return MockResponse(None, 403)
     elif args[0] == f"{MOCK_API_BASE_URL}servererror":
         return MockResponse(None, 500)
+    elif args[0] == f"{MOCK_API_BASE_URL}timeout":
+        raise Timeout("Request timed out")
 
     return MockResponse(None, 404)
 
@@ -62,12 +72,6 @@ def test_happy(self, mock_get, mock_post):
         response = client.get("/happy")
         self.assertEqual(type(response), dict)
         self.assertDictEqual(response, {"foo": "bar"})
-        # called_mock_get_urls = [call.args[0] for call in mock_get.call_args_list]
-        # self.assertIn(
-        #     f"{MOCK_API_BASE_URL}happy",
-        #     called_mock_get_urls,
-        # )
-        # self.assertEqual(len(called_mock_get_urls), 1)
 
     @mock.patch("requests.get", side_effect=mocked_requests_get)
     @mock.patch("requests.post", side_effect=mocked_requests_post)
@@ -83,13 +87,27 @@ def test_not_found(self, mock_get, mock_post):
         with self.assertRaises(ResourceNotFound):
             client.get("/notfound")
 
+    @mock.patch("requests.get", side_effect=mocked_requests_get)
+    @mock.patch("requests.post", side_effect=mocked_requests_post)
+    def test_resource_unauthorized(self, mock_get, mock_post):
+        client = SimpleJsonApiClient(MOCK_API_BASE_URL)
+        with self.assertRaises(ResourceUnauthorized):
+            client.get("/unauthorized")
+
     @mock.patch("requests.get", side_effect=mocked_requests_get)
     @mock.patch("requests.post", side_effect=mocked_requests_post)
     def test_resource_forbidden(self, mock_get, mock_post):
         client = SimpleJsonApiClient(MOCK_API_BASE_URL)
         with self.assertRaises(ResourceForbidden):
             client.get("/forbidden")
 
+    @mock.patch("requests.get", side_effect=mocked_requests_get)
+    @mock.patch("requests.post", side_effect=mocked_requests_post)
+    def test_resource_timeout(self, mock_get, mock_post):
+        client = SimpleJsonApiClient(MOCK_API_BASE_URL)
+        with self.assertRaises(Timeout):
+            client.get("/timeout")
+
     @mock.patch("requests.get", side_effect=mocked_requests_get)
     @mock.patch("requests.post", side_effect=mocked_requests_post)
     def test_other_exception(self, mock_get, mock_post):
diff --git a/tna_utilities/api.py b/tna_utilities/api.py
@@ -1,5 +1,5 @@
 import requests
-from requests import JSONDecodeError, Response, Timeout, TooManyRedirects, codes
+from requests import JSONDecodeError, Response, codes
 
 
 class ResourceNotFound(Exception):
@@ -10,6 +10,10 @@ class ResourceForbidden(Exception):
     pass
 
 
+class ResourceUnauthorized(Exception):
+    pass
+
+
 class SimpleJsonApiClient:
     """
     A simple JSON API client that provides basic functionality for making GET requests to a specified API endpoint.
@@ -19,101 +23,119 @@ class SimpleJsonApiClient:
     The client also includes error handling for connection issues, timeouts, and non-JSON responses.
 
     :param api_url: The base URL of the API.
-    :param defaultHeaders: Optional dictionary of default headers to include in every request.
-    :param defaultParams: Optional dictionary of default parameters to include in every request.
+    :param default_headers: Optional dictionary of default headers to include in every request.
+    :param default_params: Optional dictionary of default parameters to include in every request.
     """
 
     def __init__(
-        self, api_url: str, defaultHeaders: dict = {}, defaultParams: dict = {}
+        self, api_url: str, default_headers: dict = {}, default_params: dict = {}
     ):
         self.api_url: str = api_url.rstrip("/")
         self.headers: dict = (
             {
                 "Cache-Control": "no-cache",
                 "Accept": "application/json",
             }
-            if defaultHeaders
-            else defaultHeaders
+            if default_headers
+            else default_headers
         )
-        self.params: dict = defaultParams
+        self.params: dict = default_params
 
-    def add_parameter(self, key: str, value):
+    def add_default_parameter(self, key: str, value) -> "SimpleJsonApiClient":
         """
-        Add a single parameter to the request.
+        Add a single default parameter to the requests.
         """
 
         self.params[key] = value
+        return self
 
-    def add_parameters(self, params: dict):
+    def add_default_parameters(self, params: dict) -> "SimpleJsonApiClient":
         """
-        Add multiple parameters to the request.
+        Add multiple default parameters to the requests.
         """
 
         self.params = self.params | params
+        return self
 
-    def add_header(self, key: str, value):
+    def add_default_header(self, key: str, value) -> "SimpleJsonApiClient":
         """
-        Add a single header to the request.
+        Add a single default header to the requests.
         """
 
         self.headers[key] = value
+        return self
 
-    def add_headers(self, headers: dict):
+    def add_default_headers(self, headers: dict) -> "SimpleJsonApiClient":
         """
-        Add multiple headers to the request.
+        Add multiple default headers to the requests.
         """
 
         self.headers = self.headers | headers
+        return self
+
+    def _normalise_url(self, path: str) -> str:
+        """
+        Normalise a URL, avoiding duplicated slashes
+        """
 
-    def get(self, path: str = "/"):
+        return f"{self.api_url}/{path.lstrip('/')}"
+
+    def get(
+        self,
+        path: str = "/",
+        params: dict | None = None,
+        headers: dict | None = None,
+        timeout: int = 10,
+    ) -> dict:
         """
         Make a GET request to the specified path of the API endpoint.
+
+        :param path: The path to append to the base API URL for the request.
+        :param params: Optional dictionary of query parameters to include in the request. These will be merged with any default parameters set for the client.
+        :param headers: Optional dictionary of headers to include in the request. These will be merged with any default headers set for the client.
         """
 
-        url = f"{self.api_url}/{path.lstrip('/')}"
-        try:
-            response = requests.get(
-                url,
-                params=self.params,
-                headers=self.headers,
-            )
-        except ConnectionError:
-            raise Exception("A connection error occured")
-        except Timeout:
-            raise Exception("The request timed out")
-        except TooManyRedirects:
-            raise Exception("Too many redirects")
-        except Exception as e:
-            raise Exception(e)
+        url = self._normalise_url(path)
+        response = requests.get(
+            url,
+            params=self.params if params is None else {**self.params, **params},
+            headers=self.headers if headers is None else {**self.headers, **headers},
+            timeout=timeout,
+        )
         return self._handle_response(response)
 
     def post(
-        self, path: str = "/", data: dict | None = None, json: dict | str | None = None
-    ):
+        self,
+        path: str = "/",
+        data: dict | None = None,
+        json: dict | str | None = None,
+        params: dict | None = None,
+        headers: dict | None = None,
+        timeout: int = 10,
+    ) -> dict:
         """
         Make a POST request to the specified path of the API endpoint.
+
+        :param path: The path to append to the base API URL for the request.
+        :param data: Optional dictionary, list of tuples, bytes, or file-like
+        object to include in the request body.
+        :param json: Optional JSON serialisable Python object to send in the request body.
+        :param params: Optional dictionary of query parameters to include in the request. These will be merged with any default parameters set for the client.
+        :param headers: Optional dictionary of headers to include in the request. These will be merged with any default headers set for the client.
         """
 
-        url = f"{self.api_url}/{path.lstrip('/')}"
-        try:
-            response = requests.post(
-                url,
-                params=self.params,
-                headers=self.headers,
-                data=data,
-                json=json,
-            )
-        except ConnectionError:
-            raise Exception("A connection error occured")
-        except Timeout:
-            raise Exception("The request timed out")
-        except TooManyRedirects:
-            raise Exception("Too many redirects")
-        except Exception as e:
-            raise Exception(e)
+        url = self._normalise_url(path)
+        response = requests.post(
+            url,
+            params=self.params if params is None else {**self.params, **params},
+            headers=self.headers if headers is None else {**self.headers, **headers},
+            data=data,
+            json=json,
+            timeout=timeout,
+        )
         return self._handle_response(response)
 
-    def _handle_response(self, response: Response):
+    def _handle_response(self, response: Response) -> dict:
         """
         Handle the API response, checking for common HTTP status codes and returning the JSON content if the request was successful.
         """
@@ -125,8 +147,10 @@ def _handle_response(self, response: Response):
                 raise Exception("Non-JSON response provided")
         if response.status_code == 400:
             raise Exception("Bad request")
+        if response.status_code == 401:
+            raise ResourceUnauthorized("Unauthorised")
         if response.status_code == 403:
             raise ResourceForbidden("Forbidden")
         if response.status_code == 404:
             raise ResourceNotFound("Resource not found")
-        raise Exception("Request failed")
+        raise Exception(f"Request failed with {response.status_code}")
