We've come a really long way in this series of blog posts, we've now covered a majority of the functionality in the 5.2 release through the following posts:
- Part 1 - Introduction
- Part 2 - Navigation
- Part 3 - Creating Nodes
- Part 4 - Managing Nodes
- Part 5 - Versioning & Locking
- Part 6 - Associations
- Part 7 - Collaboration
- Part 8 - Sites
- Part 9 - Queries & Search
- Part 10 - People
- Part 11 - Trashcan
- Part 12 - Discovery
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.
1. Tickets
Throughout this series we've used basic authentication in all the examples. The APIs also support the Alfresco ticket mechanism. You can POST the following body to http://localhost:8080/alfresco/api/-default-/public/authentication/versions/1/tickets to create a new ticket (1st request in the Postman collectionπ
{
"userId": "test",
"password": "test"
}ββββββββββββββββββββββββββββββββββββββββββββββββββββThe response provides the ticket in the id property:
{
"entry": {
"id": "TICKET_ed4981b4bbb15fc2713f7caaffd23982d0dd4e5c",
"userId": "test"
}
}ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ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.
The 2nd request in the Postman collection (http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?maxItems... ) shows how you can limit the number of results to five.
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.
The 3rd request in the Postman collection (http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?skipCoun... ) shows how you can skip the first two results.
This query parameter is supported across all collection endpoints.
4. Ordering results
By default all collection endpoints (those returning a list of results) have a default sort order, it's possible to change the sort order on some endpoints via the orderBy query parameter.
The 4th request in the Postman collection (http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?orderBy=...) shows how you can order the nodes in your home folder by the size of the content, starting with the largest item.
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 allows you to provide one or more clauses defining what items you want to see in the response. The 5th request in the Postman collection (http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?where=(i...) shows how you can limit the nodes in your home folder to just the files.
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.
The 6th request in the Postman collection (http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?include=...) shows how you can also include the properties and aspects for each node in your home folder when listing it's children.
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 7th request in the Postman collection (http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?fields=i... ) shows you can limit the response to only contain the id and name properties as shown in the response below:
{
"list": {
"pagination": {
"count": 3,
"hasMoreItems": false,
"totalItems": 3,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"name": "A Folder",
"id": "a5634765-ab0f-438a-8efd-bfa4139da8aa"
}
},
{
"entry": {
"name": "lorem-ipsum.txt",
"id": "5516aca4-df8b-43e8-8ff3-707316c60c6e"
}
},
{
"entry": {
"name": "image.jpg",
"id": "fc132aa5-6281-40bf-adee-5731e6ecb653"
}
}
]
}
}βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ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.
The 8th request in the Postman collection (http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people/-me- ) shows how this can be used to retrieve the profile information of the currently authenticated user.
9. Create multiple entities
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.
The 9th request in the Postman collection (http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children) shows how two folders can be created with the one request by passing the body shown below:
[
{
"name": "Folder One",
"nodeType": "cm:folder"
},
{
"name": "Folder Two",
"nodeType": "cm:folder"
}
]ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββThe API returns a standard listing response providing the details on each entity that was created, in this case, the two folders:
{
"list": {
"pagination": {
"count": 2,
"hasMoreItems": false,
"totalItems": 2,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"aspectNames": [
"cm:auditable"
],
"createdAt": "2017-04-12T10:31:12.477+0000",
"isFolder": true,
"isFile": false,
"createdByUser": {
"id": "test",
"displayName": "Test User"
},
"modifiedAt": "2017-04-12T10:31:12.477+0000",
"modifiedByUser": {
"id": "test",
"displayName": "Test User"
},
"name": "Folder One",
"id": "ecbec6fd-a273-4978-9b95-00a8e783948e",
"nodeType": "cm:folder",
"parentId": "062b8b2a-aa7e-4cdd-bfec-7fbcd16ecd85"
}
},
{
"entry": {
"aspectNames": [
"cm:auditable"
],
"createdAt": "2017-04-12T10:31:12.501+0000",
"isFolder": true,
"isFile": false,
"createdByUser": {
"id": "test",
"displayName": "Test User"
},
"modifiedAt": "2017-04-12T10:31:12.501+0000",
"modifiedByUser": {
"id": "test",
"displayName": "Test User"
},
"name": "Folder Two",
"id": "18c82e9b-5a2f-44bf-bc77-1aca7346a24a",
"nodeType": "cm:folder",
"parentId": "062b8b2a-aa7e-4cdd-bfec-7fbcd16ecd85"
}
}
]
}
}ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ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 last request in the Postman collection (http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?includeS...) shows how you'd include details of the users home folder when listing it's children, shown below in the source property:
{
"list": {
"pagination": {
"count": 12,
"hasMoreItems": false,
"totalItems": 12,
"skipCount": 0,
"maxItems": 100
},
"entries": [ ... ],
"source": {
"name": "test",
"createdAt": "2017-02-20T11:01:39.647+0000",
"modifiedAt": "2017-04-12T10:31:12.509+0000",
"createdByUser": {
"id": "admin",
"displayName": "Administrator"
},
"modifiedByUser": {
"id": "test",
"displayName": "Test User"
},
"isFolder": true,
"isFile": false,
"aspectNames": [
"cm:ownable",
"cm:auditable"
],
"properties": {
"cm:owner": {
"id": "test",
"displayName": "Test User"
}
},
"nodeType": "cm:folder",
"parentId": "a9ad3bc4-d30f-4910-bee0-63d497e74a22",
"id": "062b8b2a-aa7e-4cdd-bfec-7fbcd16ecd85"
}
}
}ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββAnother example is returning details of a site when listing it's members, to do that you'd use the following URL: http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/sites/swsdp/members?includeS...
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.
2 Comments
