Endpoints¶

class apiron.endpoint.Endpoint(path: str = '/', default_method: str = 'GET', default_params: Optional[Dict[str, Any]] = None, required_params: Optional[Iterable[str]] = None, return_raw_response_object: bool = False, timeout_spec: Optional[apiron.client.Timeout] = None, retry_spec: Optional[urllib3.util.retry.Retry] = None)¶

Bases: object

A basic service endpoint that responds with the default Content-Type for that endpoint

Parameters

path (str) – The URL path for this endpoint, without the protocol or domain
default_method (str) – (Default 'GET') The default method to use when calling this endpoint.
default_params (dict) – The default parameters to use when calling this endpoint. Useful when an endpoint always or most often needs a base set of parameters supplied.
required_params – An iterable of required parameter names. Calling an endpoint without its required parameters raises an exception.
return_raw_response_object (bool) – Whether to return a requests.Response object or call format_response() on it first. This can be overridden when calling the endpoint. (Default False)
timeout_spec (Timeout) – (optional) An override of the timeout behavior for calls to this endpoint. (default None)
retry_spec (urllib3.util.retry.Retry) – (optional) An override of the retry behavior for calls to this endpoint. (default None)

format_response(response: requests.models.Response) → Union[str, Dict[str, Any], Iterable[bytes]]¶

Extracts the appropriate type of response data from a requests.Response object

Parameters: response (requests.Response) – The original response from requests
Returns: The response’s text content
Return type: str

get_formatted_path(**kwargs) → str¶

Format this endpoint’s path with the supplied keyword arguments

Returns: The fully-formatted path
Return type: str

get_merged_params(supplied_params: Optional[Dict[str, Any]] = None) → Dict[str, Any]¶

Merge this endpoint’s default parameters with the supplied parameters

Parameters: supplied_params (dict) – A dictionary of query parameter, value pairs
Returns: A dictionary of this endpoint’s default parameters, merged with the supplied parameters. Any default parameters which have a value supplied are overridden.
Return type: dict
Raises: apiron.exceptions.UnfulfilledParameterException – When a required parameter for this endpoint is not a default param and is not supplied by the caller

property path_placeholders: List[str]¶

The formattable placeholders from this endpoint’s path, in the order they appear.

Example:

>>> endpoint = Endpoint(path='/api/{foo}/{bar}')
>>> endpoint.path_placeholders
['foo', 'bar']

property required_headers: Dict[str, Any]¶

Generates the headers that must be sent to this endpoint based on its attributes

Returns: Header name, header value pairs
Return type: dict

class apiron.endpoint.JsonEndpoint(*args, path: str = '/', default_method: str = 'GET', default_params: Optional[Dict[str, Any]] = None, required_params: Optional[Iterable[str]] = None, preserve_order: bool = False)¶

Bases: apiron.endpoint.endpoint.Endpoint

An endpoint that returns application/json

Parameters

path (str) – The URL path for this endpoint, without the protocol or domain
default_method (str) – (Default 'GET') The default method to use when calling this endpoint.
default_params (dict) – The default parameters to use when calling this endpoint. Useful when an endpoint always or most often needs a base set of parameters supplied.
required_params – An iterable of required parameter names. Calling an endpoint without its required parameters raises an exception.
return_raw_response_object (bool) – Whether to return a requests.Response object or call format_response() on it first. This can be overridden when calling the endpoint. (Default False)
timeout_spec (Timeout) – (optional) An override of the timeout behavior for calls to this endpoint. (default None)
retry_spec (urllib3.util.retry.Retry) – (optional) An override of the retry behavior for calls to this endpoint. (default None)

format_response(response) → Dict[str, Any]¶

Extracts JSON data from the response

Parameters: response (requests.Response) – The original response from requests
Returns: The response’s JSON content
Return type: dict if preserve_order is False
Return type: collections.OrderedDict if preserve_order is True

property required_headers: Dict[str, str]¶

Generates the headers that must be sent to this endpoint based on its attributes

Returns: Header name, header value pairs
Return type: dict

class apiron.endpoint.StreamingEndpoint(path: str = '/', default_method: str = 'GET', default_params: Optional[Dict[str, Any]] = None, required_params: Optional[Iterable[str]] = None, return_raw_response_object: bool = False, timeout_spec: Optional[apiron.client.Timeout] = None, retry_spec: Optional[urllib3.util.retry.Retry] = None)¶

Bases: apiron.endpoint.endpoint.Endpoint

An endpoint that streams data incrementally

Parameters

path (str) – The URL path for this endpoint, without the protocol or domain
default_method (str) – (Default 'GET') The default method to use when calling this endpoint.
default_params (dict) – The default parameters to use when calling this endpoint. Useful when an endpoint always or most often needs a base set of parameters supplied.
required_params – An iterable of required parameter names. Calling an endpoint without its required parameters raises an exception.
return_raw_response_object (bool) – Whether to return a requests.Response object or call format_response() on it first. This can be overridden when calling the endpoint. (Default False)
timeout_spec (Timeout) – (optional) An override of the timeout behavior for calls to this endpoint. (default None)
retry_spec (urllib3.util.retry.Retry) – (optional) An override of the retry behavior for calls to this endpoint. (default None)

format_response(response) → Iterable[bytes]¶

Stream response in chunks

Parameters: response (requests.Response) – The original response from requests
Returns: The response’s content
Return type: generator

class apiron.endpoint.StubEndpoint(stub_response: Optional[Any] = None, **kwargs)¶

Bases: apiron.endpoint.endpoint.Endpoint

A stub endpoint designed to return a pre-baked response

The intent is to allow for a service to be implemented before the endpoint is complete.

Parameters

stub_response –
A pre-baked response or response-determining function. Pre-baked response example: 'stub response' or {'stub': 'response'} A response-determining function may operate on any arguments provided to the client’s call method. Example of a response-determining function:
```
def stub_response(**kwargs):
    if kwargs.get('params') and kwargs['params'].get('param_key') == 'param_value':
        return {'stub response': 'for param_key=param_value'}
    else:
        return {'default': 'response'}
```
**kwargs – Arbitrary parameters that can match the intended real endpoint. These don’t do anything for the stub but streamline the interface.