Endpoints

class apiron.endpoint.Endpoint(path='/', default_method='GET', default_params=None, required_params=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.
format_response(response)

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)

Format this endpoint’s path with the supplied keyword arguments

Returns:The fully-formatted path
Return type:str
get_merged_params(supplied_params=None)

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
path_placeholders

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']
required_headers

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='/', default_method='GET', default_params=None, required_params=None, preserve_order=False)

Bases: apiron.endpoint.endpoint.Endpoint

An endpoint that returns application/json

format_response(response)

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
required_headers

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='/', default_method='GET', default_params=None, required_params=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.
format_response(response)

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=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.