Overall API concepts
Pages 17
Clone this wiki locally
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.
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
Web: https://xamoom.com - Email: mailto:support@xamoom.com