Organisation of Data in the API

Overview

The Kalibrate Data API provides a set of RESTful web service endpoints to retrieve, create and update and import pricing and reference data. It includes a simple but powerful query language that allows for the filtering and sorting of data, and allows the caller to specify retrieval of a subset of attributes.

Document Database

The Data API uses Microsoft Azure Cosmos DB as its underlying data store. Azure Cosmos DB is a globally distributed, multi-model database service that provides enormous capacity, scalability and resilience.

Cosmos DB stores documents in collections. Documents within a single collection can readily use different models. The only constraint is ensuring that each document within a collection contains an identifier unique to that collection

Collections

The Data API exposes a RESTful web service API that allows the retrieval of data using JavaScript Object Notation (JSON) documents as results of queries that are submitted to the API.

The API exposes Endpoints that correlate to collections of “logically”-related data (Entities) which are grouped together for convenience.

Collections are heterogenous, in that we store multiple different document formats that represent the different discrete types (Variants) of documents within a Collection.

For example, the “Price” collection contains Price Entities of 13 different Variants all logically grouped together so that Entities of different Variants can be retrieved in single query (eg. “Competitor” and “Own" prices).

Name	Description
Price	Own, Competitor, Proposed, Cost, Dealer etc. prices
Price Request	All entities related to a Price Request
Product	Global, Own and Competitor product data
ProductGroup	Product Group data
Reference	All Reference and associational data
Site	Own Site, Competitor Site and Own Site Competitor data
Survey History	All entities related to Survey History
Volume	Sales, Plan, Forecast, Projected etc. Volumes

Documents

Every document stored within the database, regardless of the collection it belongs to, it's type, or variant, consists of two "blocks" of information.

The ID block which contains meta-data about the specific document, and The Data block which contains the actual attributes of the entity

The ID block contains the same list of attributes, regardless of the collection or entity. The ID attributes are:

Property name	Description
entityId	The universally unique identifier (UID) for this Entity
entityVersion	The specific version of the Entity in the database
tenantId	The identifier of the tenant (customer) that the data belongs to. Data can only be retrieved from authorized tenants, and this is enforced in the authorization layer.
collection	The Collection to which the Entity belongs
entityType	The general type of the Entity within the Collection. Collections can support multiple general Entity types (eg. “Price”)
entityVariant	The specific Variant of the Entity type within a Collection (eg. “Own”).
entityOrigin	Where the Entity data originated from (eg. “import”, “bulk upload”, “user action”)
createdOn	The date that this version of the Entity was created
updatedOn	The date that the Entity version was updated

The Data block is different for each entity variant within a collection.

For a complete list of entities click here

The developer swagger documentation for the Sandpit Environment

Embedded Documents

Each data block will generally consist of an array of simple JSON attributes and values. e.g:

{
    "name":"Own Site #0001"
}

The Data API does however support nested entities, a.k.a Embedded Documents, for example:

{
    "status":{
        "exported":true,
        "approved":false
    }
}

Embedded documents or nested entities, can be referred to in filter requests just as root attributes can, for example:

/api/price?query=(status.exported=true)

Document References

Kalibrate makes use of this feature when resolving the Kalibrate Pricing relation database model to the Collection and Document oriented model of the API.

We use a standard embedded reference format for every relational item that belongs to an entity. This standard format is:

"<embedded attribute name>": {
    "entityId": <globally unique identifier of the child/embedded document>
    "reference": <path to the item in the API>,
    "body": <this is reserved for future iterations of the API and will be empty>
}

An example of a populated embedded document might be:

"priceRequest": {
    "entityId": "5ed55abe-ae97-49fa-b205-06e4e680b9a1",
    "reference": "/priceRequest/5ed55abe-ae97-49fa-b205-06e4e680b9a1",
    "body": {}
}