Python API reference

Client

class zds_client.client.Client(api_root: str, oas_location: str = '', auth: Union[zds_client.auth.ClientAuth, NoneType] = None, operation_suffix_mapping: Dict[str, str] = <factory>, request_hooks: Union[Dict[str, Callable[..., Any]], NoneType] = None)

api_root: str: Fully qualified base URL of the API/service, e.g. "https://example.com/api/v1/".

oas_location: str = ''

Relative location of the OpenAPI spec.

By default, it is assumed the API spec is hosted at the API root.

operation_suffix_mapping: Dict[str, str]

Mapping of semantic RESTful operations to the operation-IDs used in the API spec.

TODO: make this more robust - operationId is an _optional_ key and may be empty.

request_hooks: Optional[Dict[str, Callable[[...], Any]]] = None

requests library hooks to apply for every request.

See https://requests.readthedocs.io/en/latest/user/advanced/#event-hooks for details. You can use this to set up request logging or middleware-like processing to the responses.

property schema: dict

pre_request(method: str, url: str, kwargs: Optional[dict] = None) → Any

Perform any pre-request processing required.

The kwargs are literally passed to the underlying requests call and may be mutated in place.

The return value is passed as first argument to post_response().

request(path: str, operation: str, method='GET', expected_status=200, request_kwargs: Optional[dict] = None, **kwargs) → Optional[Union[List[Dict[str, Any]], Dict[str, Any]]]

Make the HTTP request using requests.

The URL is created based on the path and base URL and any defaults from the OAS schema are injected.

Returns: a list or dict, the result of calling response.json()
Raises: requests.HTTPException for internal server errors
Raises: ClientError for HTTP 4xx status codes

post_response(pre_id: Any, response_data: Optional[Union[dict, list]] = None) → None

list(resource: str, params=None, request_kwargs: Optional[dict] = None, **path_kwargs) → List[Dict[str, Any]]

__init__(api_root: str, oas_location: str = '', auth: ~typing.Optional[~zds_client.auth.ClientAuth] = None, operation_suffix_mapping: ~typing.Dict[str, str] = <factory>, request_hooks: ~typing.Optional[~typing.Dict[str, ~typing.Callable[[...], ~typing.Any]]] = None) → None

retrieve(resource: str, url=None, request_kwargs: Optional[dict] = None, **path_kwargs) → Dict[str, Any]

create(resource: str, data: dict, request_kwargs: Optional[dict] = None, **path_kwargs) → Dict[str, Any]

update(resource: str, data: dict, url=None, request_kwargs: Optional[dict] = None, **path_kwargs) → Dict[str, Any]

partial_update(resource: str, data: dict, url=None, request_kwargs: Optional[dict] = None, **path_kwargs) → Dict[str, Any]

delete(resource: str, url=None, request_kwargs: Optional[dict] = None, **path_kwargs) → Dict[str, Any]

operation(operation_id: str, data: dict, method='POST', url=None, request_kwargs: Optional[dict] = None, **path_kwargs) → Union[List[Dict[str, Any]], Dict[str, Any]]

Client authentication

class zds_client.auth.ClientAuth(client_id: str, secret: str, user_id: str = '', user_representation: str = '', **claims)

Auth for the ZDS client, using JWT.

Usage:

>>> auth = ClientAuth(
        client_id="zrc",
        secret="my-secret",
        user_id="my-id",
        user_representation="my-name"
    )
>>> auth.credentials()
{
    'Authorization': '<base64>.<base64>.<base64>'
}
>>> requests.get(url, **auth.credentials())

TODO: make pluggable and implement some common auth schemes.

__init__(client_id: str, secret: str, user_id: str = '', user_representation: str = '', **claims): Initialize the client authentication configuration.

credentials() → dict: Return the HTTP Header containing the credentials.

Schema fetching

Manage OpenAPI Specification 3.0.x schemas.

zds_client.oas.schema_fetcher = <zds_client.oas.SchemaFetcher object>

Sentinel schema fetcher instance, used by zds_client.client.Client.

Note that you can mutate schema_fetcher.cache to replace it with another cache backend, for example.

class zds_client.oas.SchemaFetcher

Retrieve and cache OpenAPI Specification schemas

Caching is done based on the URL of the schema. The schema is parsed from YAML and the resulting dictionary is returned/stored.

fetch(url: str, *args, **kwargs) → dict

Fetch a YAML-based OAS 3.0.x schema.

Any extra arguments or keyword arguments are forwarded to requests.get().

Parameters: url – The URL to the schema, must point to a YAML object
Raises: requests.RequestException if the URL doesn’t properly resolve
Raises: ValueError if the API-spec is not a OAS 3.0.x spec