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 MethodOperation
GETRetrieve a element or list of elements
POSTCreate a new element or a child entry in a element
PUTUpdate a element
DELETEDelete 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.

RequestFormatContent-TypeFileUpload
JSONapplication/jsonNO
Form Urlencodedapplication/x-www-form-urlencodedNO
Multipart Form Datamultipart/form-dataYES

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 <response_format> mentioned under Resource URIs.

Response FormatSpecified in URI asResponse Content-Type
JSONjsonapplication/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.

TypeDescription
StringString type with Unicode support
IntegerSigned 64 bit integral number
IDSpecial type of Integer with minimum value 1, Will be unique within each resource type
FloatFloating point number
BooleanTrue/False type
DateTimeCombined 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
DateDate 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 FormatNULL Value Representation
JSONnull

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

FieldTypeDescription
sizeIntegerThe number of items per page (limited to the maximum defined for the particular collection resource)
pageIntegerThe number of the page required

Paginated List - Response Data Structure

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

FieldTypeDescription
page_infoPage InfoInformation about the pagination
dataList of ElementsThe 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.

FieldTypeDescription
countIntegerNumber of elements returned
start_indexIntegerThe index of the first element in the returned subset
end_indexIntegerThe index of the last element in the returned subset
last_indexIntegerThe index of the last element in the entire collection
page_countIntegerNumber 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.

FieldTypeDescription
fieldStringThe name of the field. (For errors that pertain to the entire request and not to a particular field, the field name will be "__all__")
errorsList of StringOne or more errors related to the field value