Protocols

This section of the document describes the communication protocol, data formats and application mechanisms used in the API.

Request Methods

The following HTTP methods are used to perform operations on resources provided by the API.

NOTE: not all resources support all the listed operations, see the documentation of each resource for the supported methods

HTTP Method Operation
GET Retrieve a element or list of elements
POST Create a new element or a child entry in a element
POST Update a element
DELETE Delete a element

Request Content Types

The following data formats are supported by the API server when data is sent to it for POST and PUT operations. Any of the data formats can be used provided the correct Content-Type is set in the HTTP request header.

NOTE: file uploads are only supported with Multipart Form Data.

RequestFormat Content-Type FileUpload
JSON application/json NO
Form Urlencoded application/x-www-form-urlencoded NO
Multipart Form Data multipart/form-data YES

Response Content Types

The following data formats are supported for response data sent back by the API server. The required data format is specified as the mentioned under Resource URIs.

Response Format Specified in URI as Response Content-Type
JSON json application/json

Data Types

These are the basic data types that are used in the API. Using these types more complex data structures for the resources are built.

Type Description
String String type with Unicode support
Integer Signed 64 bit integral number
ID Special type of Integer with minimum value 1, Will be unique within each resource type
Float Floating point number
Boolean True/False type
DateTime

Combined date and time in the ISO 8601 extended format of YYYY-MM-DD HH:MM:SS.ssssss

NOTES:

1. All DateTime values in the API are in UTC timezone

2. The decimal part represented by ssssss is optional

3. A space separator is used between the date and time values

Date

Date in the ISO 8601 extended format of YYYY-MM-DD

NOTE: all Date values in the API are inUTC timezone

NULL Values

Some of the fields in a resource may be optional or currently absent . The values of these fields are represented as a special NULL value. This value maps to corresponding equivalents in the data formats as listed below.

Response Format NULL Value Representation
JSON null

Paginated Lists for Collection Resources

Some of the collection resources provided by the API may return a large volume of elements. In these cases the API imposes a upper limit on the number elements that can be returned in a single collection read request.

By specifying a page size (lesser than or equal to the upper limit) and a corresponding page number as URL parameters, the collection can be split the into a smaller number of elements and progressively retrieved from the API server.

The response from the API server contains information about the page split and the actual data as described below.

URL Parameters

Field Type Description
size Integer The number of items per page (limited to the maximum defined for the particular collection resource)
page Integer The number of the page required

Paginated List - Response Data Structure

This data structure contains information and data from the paginated list.

Field Type Description
page_info Page Info Information about the pagination
data List of Elements The list of elements retrieved from the collection

Page Info - Inner Data Structure

This inner data structure is used in the "page_info" field of a Paginated List.

Field Type Description
count Integer Number of elements returned
start_index Integer The index of the first element in the returned subset
end_index Integer The index of the last element in the returned subset
last_index Integer The index of the last element in the entire collection
page_count Integer Number of pages for the given page size

Data Validation Errors

The API server performs validation on the data submitted via POST and PUT requests. In case the data validation fails, the API server returns HTTP response code 400 along with error information in the response body.

The error information response data is a List of Field Errors that contains information about data validation errors in individual fields as well as any errors that apply to the entire request (like errors that are not dependent on individual fields).

Field Errors - Response Data Structure

This data structure contains the field name and the list of errors messages for the field.

Field Type Description
field String The name of the field. (For errors that pertain to the entire request and not to a particular field, the field name will be "__all__")
errors List of String One or more errors related to the field value