API Reference

Tiny API Client

The short and sweet way to create an API client

Basic usage:
>>> from tiny_api_client import api_client, get
>>> @api_client("https://example.org/api")
... class MyClient:
...     @get("/profile/{user_id}")
...     def fetch_profile(response):
...        return response
>>> client = MyClient()
>>> client.fetch_profile(user_id=...)
tiny_api_client.api_client(url: str | None = None, /, *, max_retries: int | Retry = 0, timeout: int | None = None, status_handler: Callable[[Any, Any, Any], None] | None = None, status_key: str = 'status', results_key: str = 'results') → Callable[[APIClient], APIClient]

Annotate a class to use the api client method decorators

Basic usage:
>>> @api_client("https://example.org/api")
>>> class MyClient:
...     ...
Parameters:

  • url (str) – The root URL of the API server

  • max_retries (int) – Max number of retries for network errors

  • timeout (int) – Timeout for requests in seconds

  • status_handler (Callable) – Error handler for status codes

  • status_key (str) – Key of response that contains status codes

  • results_key (str) – Key of response that contains results

tiny_api_client.delete(route: str, *, version: int = 1, use_api: bool = True, json: bool = True, xml: bool = False, **request_kwargs: Any) → RequestDecorator

Declare an endpoint with the given HTTP method and parameters

Basic usage:
>>> from tiny_api_client import get, post
>>> @get("/posts")
... def get_posts(self, response):
...     return response
>>> @post("/posts")
... def create_post(self, response):
...     return response
Parameters:

  • endpoint (str) – Endpoint including positional placeholders

  • version (int) – Replaces version placeholder in API URL

  • json (bool) – Toggle JSON parsing of response

  • xml (bool) – Toggle XML parsing of response

  • request_kwargs (dict) – Any keyword arguments passed to requests

tiny_api_client.get(route: str, *, version: int = 1, use_api: bool = True, json: bool = True, xml: bool = False, **request_kwargs: Any) → RequestDecorator

Declare an endpoint with the given HTTP method and parameters

Basic usage:
>>> from tiny_api_client import get, post
>>> @get("/posts")
... def get_posts(self, response):
...     return response
>>> @post("/posts")
... def create_post(self, response):
...     return response
Parameters:

  • endpoint (str) – Endpoint including positional placeholders

  • version (int) – Replaces version placeholder in API URL

  • json (bool) – Toggle JSON parsing of response

  • xml (bool) – Toggle XML parsing of response

  • request_kwargs (dict) – Any keyword arguments passed to requests

tiny_api_client.patch(route: str, *, version: int = 1, use_api: bool = True, json: bool = True, xml: bool = False, **request_kwargs: Any) → RequestDecorator

Declare an endpoint with the given HTTP method and parameters

Basic usage:
>>> from tiny_api_client import get, post
>>> @get("/posts")
... def get_posts(self, response):
...     return response
>>> @post("/posts")
... def create_post(self, response):
...     return response
Parameters:

  • endpoint (str) – Endpoint including positional placeholders

  • version (int) – Replaces version placeholder in API URL

  • json (bool) – Toggle JSON parsing of response

  • xml (bool) – Toggle XML parsing of response

  • request_kwargs (dict) – Any keyword arguments passed to requests

tiny_api_client.post(route: str, *, version: int = 1, use_api: bool = True, json: bool = True, xml: bool = False, **request_kwargs: Any) → RequestDecorator

Declare an endpoint with the given HTTP method and parameters

Basic usage:
>>> from tiny_api_client import get, post
>>> @get("/posts")
... def get_posts(self, response):
...     return response
>>> @post("/posts")
... def create_post(self, response):
...     return response
Parameters:

  • endpoint (str) – Endpoint including positional placeholders

  • version (int) – Replaces version placeholder in API URL

  • json (bool) – Toggle JSON parsing of response

  • xml (bool) – Toggle XML parsing of response

  • request_kwargs (dict) – Any keyword arguments passed to requests

tiny_api_client.put(route: str, *, version: int = 1, use_api: bool = True, json: bool = True, xml: bool = False, **request_kwargs: Any) → RequestDecorator

Declare an endpoint with the given HTTP method and parameters

Basic usage:
>>> from tiny_api_client import get, post
>>> @get("/posts")
... def get_posts(self, response):
...     return response
>>> @post("/posts")
... def create_post(self, response):
...     return response
Parameters:

  • endpoint (str) – Endpoint including positional placeholders

  • version (int) – Replaces version placeholder in API URL

  • json (bool) – Toggle JSON parsing of response

  • xml (bool) – Toggle XML parsing of response

  • request_kwargs (dict) – Any keyword arguments passed to requests

Exceptions

class tiny_api_client.APIClientError

Base error class for the API Client

class tiny_api_client.APIEmptyResponseError

The API response is empty

class tiny_api_client.APIStatusError

The API returned an error status

class tiny_api_client.APINoURLError

The API has no URL declared