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 callformat_response()
on it first. This can be overridden when calling the endpoint. (DefaultFalse
)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
- get_formatted_path(**kwargs) str ¶
Format this endpoint’s path with the supplied keyword arguments
- Returns
The fully-formatted path
- Return type
- 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
- Raises
apiron.exceptions.UnfulfilledParameterException – When a required parameter for this endpoint is not a default param and is not supplied by the caller
- 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 callformat_response()
on it first. This can be overridden when calling the endpoint. (DefaultFalse
)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
ifpreserve_order
isFalse
- Return type
collections.OrderedDict
ifpreserve_order
isTrue
- 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 callformat_response()
on it first. This can be overridden when calling the endpoint. (DefaultFalse
)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’scall
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.