This section of the document describes the communication protocol, data formats and application mechanisms used in the API.
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
|GET||Retrieve a element or list of elements|
|POST||Create a new element or a child entry in a element|
|PUT||Update a element|
|DELETE||Delete a element|
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.
|Multipart Form Data||multipart/form-data||YES|
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 Format||Specified in URI as||Response Content-Type|
These are the basic data types that are used in the API. Using these types more complex data structures for the resources are built.
|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|
|DateTime||Combined date and time in the ISO 8601 extended format of YYYY-MM-DD HH:MM:SS.ssssss |
|Date||Date in the ISO 8601 extended format of YYYY-MM-DD|
NOTE: all Date values in the API are inUTC timezone
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|
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.
|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|
This data structure contains information and data from the paginated list.
|page_info||Page Info||Information about the pagination|
|data||List of Elements||The list of elements retrieved from the collection|
This inner data structure is used in the "page_info" field of a Paginated List.
|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|
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).
This data structure contains the field name and the list of errors messages for the field.
|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|