API class documentation

Classes related to the top-level API entry point are described here. The API class is instantiated to access subsequent API methods and provide the same hierarchy as the REST API describes. The APIChild class is used to describe common methods for entry points into the API with methods to expose GET and POST requests.

API class

class apreshttp.API(root)

Entry-point class for Python code to access HTTP ApRES API

The API class exposes the system, radar and data top-level elements of the ApRES HTTP API. It also exposes methods for assigning the API key required to perform POST requests.

POST requests are used to perform operations on the radar (such as bursts updating configuration, etc.) and as such require the API key to provided.

__init__(root)

Initialise a new instance of the API specifying the root URL

Creating a new instance of the API class requires the provision of a root URL.

The default URL used by the ApRES is

The root URL is sanitised by API.assignRootURL - see this for further information.

Parameters

root (str) – Root URL for the API to direct HTTP requests to

assignRootURL(root)

Sanitises and assigns the value in root as the root API URL

Checks whether the value in root is formatted correctly as the root URL for the API.

Values for root can be preceeded with ‘http://’ or omit the ‘http://’ protocol. Trailing forward slashes will be trimmed from the root URL if present.

Empty text at the start of the root URL is stripped, however no guarantee is given that the URL will connect when API functions are called.

Parameters

root (str) – root URL for the api (i.e. http://radar.localnet)

Raises

TypeError – raised if the root parameter is not a str

debug(*args, **kwargs)

Prints to the default system output buffer, if debug enabled

Prints to the default system output buffer, as used by the system print function.

Parameters

  • args – unpack unnamed arguments into print

  • kwargs – unpack named keywork arguments into print

resultsInterval

Interval between requests for results in seconds

setKey(key)

Sets the API key to be used during POST requests

Parameters

key (str) – string key to be used for API requests

Raises

InvalidAPIKeyException – raised if the key parameter is not a string or is empty.

timeout

HTTP timeout in seconds

wait

wait time between consecutive HTTP requests

APIChild class

class apreshttp.APIChild(api_obj)

APIChild objects provide wrappers for POST and GET requests

APIChild objects wrap the requests.get() and requests.post() methods to build classes to support the implementation of calls of GET and POST API methods.

__init__(api_obj)

Assign instance of the API class

APIChild should inherently be a child of an API object hence the constructor requires an instance of API to meet this conditions.

Parameters

api_obj (apreshttp.API) – instance of API

formCompleteURL(url_part)

Returns the full URL for the HTTP request

Combines the API root, /api/ component and final API route into a complete URL, i.e.

Parameters

url_part (str) – API route, i.e. system/reset

Returns

str

getRequest(url, data_obj=None, *args, **kwargs)

Perform a GET request to the URL, passing an API key and data

The URL should be a valid ApRES HTTP API URL as described in api_routes, without the api/ or root prefix. If the URL is not valid then a NotFoundException is raised.

HTTP arguments can be passed using the data_obj parameter as a dictionary, containing named arguments ([“name”]=value). Acceptable value types are str, float, int. This is the same as requesting a URL with a query string appended with

?name1=value1&name2=value2

Parameters

  • url (str) – URL to be requested from the API which is append to the root in the form {root}/api/{url}

  • data_obj (dict) – Name-value pairs to be passed as HTTP args

postRequest(url, data_obj=None, files_obj=None, *args, **kwargs)

Perform a POST request to the URL, passing an API key and data

The URL should be a valid ApRES HTTP API URL as described in api_routes, without the api/ or root prefix. If the URL is not valid then a NotFoundException is raised.

HTTP arguments can be passed using the data_obj parameter as a dictionary, containing named arguments ([“name”]=value). Acceptable value types are str, float, int.

If files are to be uploaded, then they should be provided to the files_obj parameter. The HTTP variable name is the dictionary key and the value is two-element tuple describing the filename and its content (i.e. [“name”] = (filename, file_content)).

Parameters

  • url (str) – URL to be requested from the API. Should not include the API root (i.e. http://radar.localnet/api/)

  • data_obj (dict) – Name-value pairs to be passed as HTTP args

  • files_obj (dict) – Dictionary of name-value pairs, where the name represents the HTTP variable name and the value is a two-element tuple of (filename, file_content)

validateResponse(response)

Takes a requests.response object and handles common errors

If the response is JSON and contains the errorCode and errorMessage keys, then parse these and raise the appropriate exceptions.

Parameters

response (request.response object) – response object returned from getRequest() or postRequest()

Raises

  • InvalidAPIKeyException – API key is invalid

  • NotFoundException – Requested URL was not found/invalid

  • InternalRadarErrorException – Problem with the radar described in the error text.

  • RadarBusyException – Radar could not perform requested task because it is busy.