-
Notifications
You must be signed in to change notification settings - Fork 1
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.
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/
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.
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.
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"
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.
There is a mechanism that allows you to serve different Content based on certain conditions. We call it Content Conditions.
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:
filter[FILTER-NAME]=FILTER-VALUE
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.
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.
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.
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