>

EntityStore API

Explained

Entitystore API

The Entitystore API is the powerhouse of all our API's. This API let's you retrieve all stored data in the MXMS system with various data structure formats at your disposal. These data structure formats all have their own unique use cases so you have the most efficient set of data available.

API Explained

All MXMS API's are built using the same philosophy. All services are ReSTful API's that use the JSON data-exchange format. All request to our API need to be authenticated using one of the possible authentication methods. If you like to read more about the various techniques click on the link below.

Different use case, different format

There not a single data structure that fits all needs or is the right one. The usefulness of a data structure depends on it's use case. A delicate balance between the data that is exposed to the client and keeping the response as small as possible. If your goal is to populate a dropdown box with some data it is not necessary to send all available data to the client.

That's why various MXMS API's provide the same datasets in different formats. Actions available might be limited on some API's. Some API's may only be read-only for example and do not have any update methods available.

Objects are exposed to an API based on the data available for an object. E.g. An object that does not contain any latitude and longitude information is not exposed to the GEO API. Want to know more about a format? Select one below!

Url format

The base url of the Entitystore API is <yourmxmsurl>/api/entitystore/<entitystore format>. Before doing any operations it is key to select the correct format for your specific use case.

Let's say our mxms url is https://www.example.com/mxms/ and we'd like to use the keyvalue format. Our endpoint url would be.

    https://www.example.com/mxms/entitystore/keyvalue/

The next thing you have to choose is which dataset you wish to retrieve. This varies for each MXMS implementation. Let's say our MXMS implementation contains products. The environment path for products would be model/product. So our complete endpoint url would be.

    https://www.example.com/mxms/entitystore/keyvalue/model/product

Authentication

Authentication information is sent by using the "Authorization" request header. The type of authentication used determines the header format. The value for the header is prefixed by the type of authentication used and followed by the authentication value. This can be an API-Key or a token. MXMS supports various authentication methods.

Manipulating your request

With the use of request headers and query string parameters you are able to fine tune your request so that only the relevant data is returned. Below is a list of the possible options.

Quicksearch

Quicksearch is a form of search were various properties are searched containing a single string value. An excellent use case is a search textbox were the user can input a search query. To use quicksearch in your API calls send the querystring parameter "q=<searchstring>".

Below is an example that quicksearches using the string value "Shoes".

    http://www.example.com/api/entitystore/keyvalue/model/product?q=Shoes

Structured query

If you need to select a specific subset of data you can use structured queries to define which data you wish to retrieve. MXMS structured query follow the LINQ (Language INtegrated Query) pattern.

You can send a structured query by sending it in the where querystring parameter.

Below is an example of a structured query. You need properly html escape the querystring, but for clarity of the example it is omitted.

    http://www.example.com/api/entitystore/keyvalue/model/product?where=City.Name=="ExampleCity" && Type == "ExampleType"

Partial Content or paged data

To retrieve a paged subset of data you can use the Range request header. If a Range header is present the status code of a successful response changes to 206 Partial Content. The server also sends the Content-Range response header to inform which indexes and the total amount of objects are on the server. Using this technique you are able to create paged data.

Below is a cUrl example of a paged request that request the first 5 items in a dataset.

    curl -X GET --header "Accept: application/json" --header "Range: entities=0-4" "http://www.example.com/api/entitystore/keyvalue/model/product"

If a Range header is present the status code of a successful response changes to 206 Partial Content. The server also sends the Content-Range response header to inform which indexes and the total amount of objects are on the server. Using this technique you are able to create paged data.

Below is a possible response from the server. Note the response header Content-Range that gives us additional information about the data returned and the total amount of items on the server. In this case the first 5 items are returned (index 0 through 4) and the server holds a total of 156 items.

    HTTP/1.1 206 Partial Content
Cache-Control: private
Content-Type: application/json
Content-Range: entities 0-4/156
Accept-Ranges: entities
Server: MXMS
Date: Mon, 16 Jan 2017 04:55:03 GMT
Content-Length: 139

[{ ... }]