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

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

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

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.