On reflection, this post should have been the first one in the series as we're going to discuss some capabilities of the API that can be applied to most endpoints! We're also going to cover some lesser know features provided by our underlying REST API Framework. The remainder of this post will highlight 10 features that we think you should know about.
To help demonstrate these we've provided a Postman collection with examples, click the "Run in Postman" button below to import it into your client.
This ticket can then be used instead of a username and password. Although the REST API supports the alf_ticket query parameter we do not recommend using it, a more secure approach is to use a HTTP header. The basic auth mechanism is still used i.e. sending an Authorisation header, however, the base64 encoded username/password is replaced with the base64 encoded ticket.
The API Explorer shows an example of this approach (select the Authentication API from the drop-down menu and expand the POST /tickets method) and all requests in the Postman collection accompanying this article use this approach.
2. Limiting results
By default the API will return a maximum of 100 results in any one request, this can be controlled via the maxItems query parameter.
This query parameter is supported across all collection endpoints.
3. Skipping results
By default the API will return results starting from the beginning, it's possible to skip any number of results using the skipCount query parameter. This is typically used for implementing paging or infinite scrolling in clients.
DESC and ASC can be used to control the direction of the sorting. As previously mentioned not all endpoints allow ordering to be controlled so you'll need to consult the API Explorer to see whether the orderBy parameter is supported and what properties within the response can be used.
5. Filtering results
Sometimes only a subset of the response is required, several endpoints support this via the where query parameter.
The where parameter is specific to each endpoint so you'll need to consult the API Explorer to see firstly, whether the where parameter is supported and secondly, what expressions and clauses can be used.
6. Requesting optional information
We have taken what we're calling a "performance first" approach with the API meaning that each endpoint, by default, only returns the information that is efficient to retrieve. If additional processing is required to obtain the information it is made available via the include query parameter.
As with orderBy and where the include parameter is specific to the endpoint so you'll need to consult the API Explorer to see what extra information is available.
7. Limiting the response
Sometimes bandwidth is a major consideration, for example, if you're building a mobile client. To cater for this scenario the API allows you to control the amount of data sent over the wire via the fields query parameter.
The fields parameter works in conjunction with the include parameter so you don't have to repeat yourself, for example, say you want to include the id, name and the optional aspectName properties in the response you can use fields=id,name&include=aspectNames, you don't have to specify aspectNames again in the fields parameter.
The fields parameter is supported universally across all endpoints.
8. -me- alias
There are several endpoints across the API that expect a person id as part of the URL, this is OK if the client knows the person id but there are some scenarios where it might not be known, for example when using tickets.
For this scenario the API supports the -me- alias which can be substituted in any URL that expects personId.
Supporting batch operations i.e. updating the metadata for multiple items simultaneously, is something we plan to support in the future, however it's a little known fact that the API already has some basic batch capabilities when it comes to creating entities.
Most POST endpoints that create entities actually allow an array of objects to be passed in the body which creates each one individually, but within the same transaction.
If the endpoint does not support creating multiple entities an error is returned.
10. Include the source entity for a collection
When returning a relationship collection of an entity, for example the children of a node or the members of a site, details of the entity are not included by default, to include them you can use the includeSource query parameter.
The includeSource parameter is supported for all endpoints that include an entity and relationship collection.
Well, that's it, we've reached the end of this series of blog posts, thank you very much if you've made it this far, we've covered a lot, but not everything! Despite the long series we've really only scratched the surface so I would definitely encourage you to experiment with the API Explorer and start building your first application.
We're always looking for feedback so please do raise any issues you encounter or any suggestions you have in JIRA and keep an eye out for more posts in the future as we enhance the v1 REST API further.