Skip to content

Overall API concepts

Bruno Hautzenberger edited this page Jan 21, 2019 · 13 revisions

All xamoom APIs follow the json:api convetions. These shared conventions, increase productivity, take advantage of generalized tooling. Before getting started with our APIs you should inform yourself about these conventions at the After you've done that keep on reading of how the xamoom APIs are structured and how we implemented these conventions for different use cases. As soon as you are familiar with everything on this page, you might want to check out all API Model Specifications.

URL structure

All xamoom API calls work the same way and also the urls to access entities are structured using the same logic. API-ENDPOINT-URL followed by the model you want to access. After that follows either a valid entity id and/or query paramters.

The API endpoint for all API calls is


Getting a content entity by id



All API calls require a valid API key bound to an active system. The API key has to be sent in Apikey HTTP Header of each and every request.

Example (cUrl)

curl -X GET -H "Content-Type: application/json" -H "Apikey:YOUR-API-KEY" ""

Mandatory API mechanisms

No matter what you are building there are two mechanisms that YOU HAVE TO implement in order to use our API. Please read these two pages very carefully and implement these things in your solution. Otherwise you will be blocked from using the API.

Conditional Content

There is a mechanism that allows you to serve different Content based on certain conditions. We call it Content Conditions.

Selecting a language

There is a special url query parameter to select a langauge. Please always include this "lang" parameter in all your calls. This tells the backend in which language you would like to recieve the data. If the item is available in the desired language it will be served to you in this language, otherwise you'll get the item in the system default language. This language value should be taken from the user's device language settings.



To filter in queries so called filters can be used as query parameters added to the request url in the following format:


Which filter can be used on which models is specified in the documentation of the API model specification.


To sort query results you can add a sort query paramters to the request url.


You can also combine sort expressions like this:


To specify the sort direction of each sort expression you can add a '+' (ASC, default) or '-' (DESC) to each sort expression.


Which sort expressions can be used on which models is specified in the documentation of the API model specification.


All queries return their results as pages. In the meta object of the response of a query you'll always find a cursor for the next page, a boolean "has-more", that tells you if there is a next page, and an attribute "total", which contains the total number of results for this query.


You can specify the page size by adding the query parameter "page[size]" to the request url. Page size defaults to 10 and is limited to a maximum of 100 entities per page.


To get the next page of a query just append the cursor you've received in the last page result in meta->cursor to the url as query parameter page[cursor]. Do not forget to keep the rest of the url the same. Also page[size] has to be the same for every page.


Stop paging as soon as a page response meta->has-more flag is false.


All errors returned by the API are returned as json:api error objects. see ->