Overall API concepts

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 jsonapi.org. 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 https://api.xamoom.net/consumer/

Example

Getting a content entity by id

GET https://api.xamoom.net/consumer/contents?id=A-VALID-CONTENT-ID&lang=de

• API-ENDPOINT-URL -> https://xamoom-217413.appspot.com/consumer/
• followed by Model -> contents
• and a valid content id as Paramter.

Authentication

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" "https://api.xamoom.net/consumer/contents?id=A-VALID-CONTENT-ID&lang=de"

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.

• Counting monthly active users and enhancing the user experience
• Setting Content Request Reasons

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.

Queries

Filtering

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

filter[FILTER-NAME]=FILTER-VALUE

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

Sorting

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

sort=SORTEXPRESSION

You can also combine sort expressions like this:

sort=SORTEXPRESSION1,SORTEXPRESSION2

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

sort=-SORTEXPRESSION1,+SORTEXPRESSION2

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

Paging

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.

{
  "cursor":"CURSOR-VALUE",
  "has-more":true,
  "total":42
}

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.

page[size]=20

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.

page[cursor]=CURSOR-VALUE

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

Errors

All errors returned by the API are returned as json:api error objects. see -> http://jsonapi.org/format/#error-objects