Following the introduction to the v1 REST API in my last post it's now time to dive in and start using the API.
Whilst the v1 REST API has had a /nodes endpoint since it's introduction in 4.2 it could not be used to navigate the repository. One of the new endpoints added in the 5.2 EA Community releases is /nodes/{id}/children which allows us to retrieve the child nodes of a folder.
All of the endpoints we'll cover in this blog post have been provided in a shared Postman collection. To import the collection into Postman click the "Run in Postman" button below.
The requests in the collection are configured to use the test user we created in the previous post.
To retrieve the children for a folder we need it's id, to help get started we have provided three aliases, -root, -my- and -shared-. As the name suggests -root- maps to the root folder of the repository, -my- maps to the currently authenticated users home on-premise and to the users private site on my.alfresco.com and finally -shared- maps to the repository's shared folder.
Let's retrieve the children of the repositories root folder, to do this we use http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-/children. If you've executed this request in Postman you should see something similar to the screenshot below (you can of course alternatively use curl or your favourite REST client).
If you've used the v1 REST API before you should recognise the collection response format. Each child node is represented within an entry object which is contained in an entries array. New v1 REST APIs are following a "performance first" principle, meaning by default, we only return the data that is the most performant to collect. More data can be requested but the client has to make a conscious decision to request more data and sacrifice a slight performance hit.
Let's build on the first request and ask for properties and a list of aspect names to be included for each node, we do that by using the new include query parameter as follows:
One of the entry objects including the extra information is shown in the response snippet below.
The 2nd request in the Postman collection can also be used to see this in action. The list of extra data that can be included is documented for each endpoint in the OpenAPI Specification, see http://localhost:8080/api-explorer/#!/nodes/getNodeChildren for an example. We'll cover customising the responses in much more detail in a future blog post.
As you'll see from the screenshot above the pagination object tells us a maximum of 100 items is returned by default, this can be controlled with the maxItems query parameter and the starting point can be controlled via the skipCount query parameter, for example, to get items 3 through 5 use the following URL (3rd request in the Postman collection):
The pagination object in the response will indicate there are more results to retrieve via the hasMoreItems property. If it's possible to determine the total number of items available the totalItems property will also be present as shown below.
The items returned can also be filtered via the where query parameter, the filtering supported is specific to each endpoint, again this is documented in the OpenAPI Specification, see [http://localhost:8080/api-explorer/#!/nodes/getNodeChildren] for an example, we'll take a look at a couple of them here.
Firstly, the isFile property can be used to just return nodes that represent content i.e. a subtype of cm:content by using the following URL (4th request in the Postman collection):
The same result can be achieved by using the isFolder property too, for example http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-/children?where=...)
As there are no files in the root of the repository we get an empty response, we'll cover creating files in the next post.
To filter the results by a specific content type nodeType can be used in the where clause, for example, to retrieve just the Sites folder use the following URL (5th request in the Postman collection):
This will result in a single result as shown below.
To retrieve all nodes of a specific type and it's sub-types use the INCLUDESUBTYPES moniker, for example where=(nodeType='my:specialNodeType INCLUDESUBTYPES')
Finally, the items returned can also be ordered via the orderBy query parameter, the ordering supported is specific to each endpoint, once again this is documented in the OpenAPI Specification, see http://localhost:8080/api-explorer/#!/nodes/getNodeChildren for an example.
By default, the nodes/{id}/children endpoint uses orderBy=isFolder DESC,name ASC as the default sort order i.e. folders first alphabetically followed by files. To mix files and folders and order them alphabetically in reverse order use the following URL (6th request in the Postman collection):
So far, we've only used -root- as the folder id, we can of course also use an explicit id, for example to retrieve the children of my Data Dictionary folder I would use the following URL:
You've now learnt how to navigate the repository, in the next post we'll see how to create files and folders.
12 Comments
We use cookies on this site to enhance your user experience
By using this site, you are agreeing to allow us to collect and use cookies as outlined in Alfresco’s Cookie Statement and Terms of Use (and you have a legitimate interest in Alfresco and our products, authorizing us to contact you in such methods). If you are not ok with these terms, please do not use this website.