Overview

Once authenticated, clients may submit requests to any of the available Endpoints to retrieve data.

The simplest method is by sending a HTTP GET request to the desired Endpoint.

Each HTTP request should be accompanies with an Authorization header that provides the bearer token.

The RAW HTTP request should look something like this:

GET /api/site?query=(entityVariant=Own)+(orderBy=createdOn)+(direction=descending)+(limit=1) HTTP/1.1
Host: dev.data.thekalibratecloud.com
Authorization: Bearer <access token>

The above example will retrieve the most recently created Own Site from the Site collection.

Filters

The Data API supports a basic filter specification that allows records to be filtered at source to restrict results retrieved from the database.

Filters can be applied to any GET request to an Endpoint, by appending a query to the request as follows:

/api/{collection}?query=({filter})

A complete example of this might be:

https://dev.data.thekalibratecloud.com/api/price?query=(entityVariant=Own)

Without a limit or offset being applied, the Data Api will return the first 1000 records for an open query.

This will retrieve 1000 “own price” records from the own price Collection, without any ordering applied see Ordering Filters

Basic filters

A basic filter is comprised of a “property name”, “comparison operator”, and “desired value”. In the above example:

entityVariant was the property name
= was the comparison operator
and Own was the desired value

The property name can be any of the general properties specified as part of all Entities, or the specific properties that belong to the Entity or Entity Variant, as described in the schema (see the appendix to this document, or the Open API documentation here.

The operator may be any of the following:

= equal to
!= not equal to
@= contains (alphanumeric values only)
> greater than (number and date types only)
< less than (number and date types only)
>= greater than or equal to
<= less than or equal to

By default, operations on alphanumeric values are case insensitive.

The desired value element of the filter should be one of:

Numeric
Alphanumeric
Unique Identifier (uuid)
Date (in YYYY-MM-DD format)
Boolean

Force String Comparison Operator (^)

The Data API will largely infer the data type from the desired value provided in the query. In certain cases (usually for strings) where the provided value is numeric but the underlying field is alphanumeric, this can lead to no results being returned for the query. In this case, we can expressly force a query to interpret the provided value as a string by prepending the Force String Comparison operator to the desired value:

/api/price?query=(importCode=^1234)

Chaining filters

It is possible to concatenate, or “chain” filters together using a chain operator. The Data API does not apply set limits to the number of links in a filter chain (other than the standard character length restrictions imposed on a URI length). V1.0 of the Data API supports filter chaining using either the “+” (AND) or “|” (OR) chain operators. To retrieve an “own price” between 1.0 and 3.0, we would use chain filters together to create:

/api/price?query=(entityVariant=Own)+(price>=1)+(price<=3)

Chain filters are applied from left to right.

Ordering filters

Calling clients can specify the ordering of data that is retrieved from the API by adding ordering filters to the end of the value filters chain. These can be applied by adding the “orderBy” filter and the “direction” filter, for example:

/api/price?query=(orderBy=createdOn)+(direction=ascending)

Attribute Filters

By default, the API will return all the available attributes in a document in the query response. It is possible to reduce the size of data returned by providing a comma separated list of desired attributes using the attributeList filter.

/api/price?query=(attributeList=name,calendarDate)

Limiting results

The Data API can hold an enormous amount of data (up to six years per tenant by default). Where an API query could potentially return a large data set, clients should employ strategies to limit the volume of data in each response. Two methods of breaking API responses down into smaller “chunks” is provided to achieve this. Failing to implement one of these methods when making such requests could result in time-outs.

Pagination filters

The first method, known as pagination, is the use of “limit” and “offset” filters that are applied as the final filters in the chain. “Limit” can be the penultimate or ultimate link in the chain but, if it is included, “offset” must always be the ultimate link in the chain. If no offset is included, 0 is assumed.

They both must always use the “+” AND operator to link them to the filter chain. Continuing the example above, the following query will retrieve 1000 more items from offset 1000.

/api/price?query=(entityVariant=Own)+(price>=1)+(price<=3)+(limit=1000)+(offset=1000)

When the API responds with fewer records than the “limit” specified in the filter, this indicates the response contains the last “chunk” of data for the query.

Pagination works well with reasonably large data sets but may not be satisfactorily performant with very large data sets. If the limit on the maximum offset value is reached, continuation tokens should be used instead.

Further reading: Microsoft Learn - OFFSET LIMIT (NoSQL query) https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/query/offset-limit

Continuation tokens

Sometimes API Call results are split over multiple pages. When this occurs, using Continuation Tokens will allow a user to limit the number of results by setting a MaxItemCount. The MaxItemCount is specified per API Call request and tells the query engine to return that number of items or fewer. If a continuation token value is returned at the end of the result set, it is an indication that there is additional data available related to the API Call. The continuation token value can be added to the next API Call. Continuation tokens will be generated until there is no longer data available relative to the API Call.

Continuation Token Setup

Set up continuation tokens on the header section of the API call. You’ll need to add two header records, x-ms-max-item-count and x-ms-continuation. Set the x-ms-max-item-count value to result limit desired and make sure the x-ms-max-item-count header record is enabled. For the first API Call, the x-ms-continuation token header will be disabled and the value will be blank (see screenshot 1). Subsequent API Calls will require the x-ms-continuation token to be enabled and the continuation token value to be placed the x-ms-continuation value field ( see screenshot 2).

First API Call (Screenshot 1)

Query Language

Second API Call (Screenshot 2)