Basic Usage

Pagination

Returned data is paginated to a maximum of 10000 items. A paginated response will contain the following:

Key	Type	Description
count	integer	Number of items returned
next	string	Url to access next set of items
previous	string	Url to access previous set of items
results	array	Array of items

Retries

At Aerobotics we strive for a highly available API, however there are times when there may be momentary operational errors (e.g. 5XX status codes), and, as a result, we recommend using Exponential Backoff when making requests.

This can be achieved by the following sample function:

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

DEFAULT_RETRIES = 4
DEFAULT_BACKOFF_FACTOR = 0.267
DEFAULT_RETRY_STATUS_FORCE_LIST = (500, 502, 504)


def requests_retry_session(retries=DEFAULT_RETRIES,
                           backoff_factor=DEFAULT_BACKOFF_FACTOR,
                           status_forcelist=DEFAULT_RETRY_STATUS_FORCE_LIST,
                           raise_on_status=False,
                           session=None):
    """ Get a retryable Python requests session

    See urllib3.util.retry.Retry for a more detailed description of the
    parameters.

    >>> from time import time
    >>> test_url = "https://httpstat.us/418"
    >>>
    >>> # Impatient retrying
    >>> retry_session_impatient = requests_retry_session(backoff_factor=0.01,
    ...                                                  retries=1,
    ...                                                  status_forcelist=(418,),
    ...                                                  raise_on_status=False)
    >>>
    >>> start = time()
    >>> retry_session_impatient.get(test_url)
    <Response [418]>
    >>> duration = time() - start
    >>> duration < 3
    True
    >>>
    >>> # Patient retrying
    >>> retry_session_patient = requests_retry_session(backoff_factor=1.0,
    ...                                                retries=4,
    ...                                                status_forcelist=(418,),
    ...                                                raise_on_status=False)
    >>>
    >>> start = time()
    >>> retry_session_patient.get(test_url)
    <Response [418]>
    >>> duration = time() - start
    >>> duration > 4
    True

    :param int retries: the number of retries
    :param float backoff_factor: the base interval for backing off
    :param tuple[int] status_forcelist: a
    :param bool raise_on_status: when the session is invoked for a request,
        if this is True and the requests fail after the specified number of
        retires, raises a urllib3.exceptions.MaxRetryError
    :param requests.Session session: the initial session to which to attach
        the retrying adapter. If not provided, creates a default
        requests.Session instance
    :return: the session
    :rtype: requests.Session
    :raises: urllib3.exceptions.MaxRetryError
    """
    session = session or requests.Session()
    retry = Retry(total=retries, read=retries, connect=retries,
                  backoff_factor=backoff_factor,
                  status_forcelist=status_forcelist,
                  raise_on_status=raise_on_status)
    adapter = HTTPAdapter(max_retries=retry)
    session.mount('http://', adapter)
    session.mount('https://', adapter)
    return session