v1 REST API - Part 2 - Navigation

cancel
Showing results for 
Search instead for 
Did you mean: 

v1 REST API - Part 2 - Navigation

gavincornwell
Senior Member
10 11 7,099

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.

button.svg

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).

Screen Shot 2016-10-13 at 21.55.21.png

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:

http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-/children?includ...

One of the entry objects including the extra information is shown in the response snippet below.

"entry": {
"aspectNames": [
"cm:titled",
"cm:auditable",
"app:uifacets"
],
"createdAt": "2016-10-05T19:44:11.127+0000",
"isFolder": true,
"isFile": false,
"createdByUser": {
"id": "System",
"displayName": "System"
},
"modifiedAt": "2016-10-05T19:44:56.559+0000",
"modifiedByUser": {
"id": "System",
"displayName": "System"
},
"name": "Data Dictionary",
"id": "0be671ab-5fd9-4cc2-b93f-10fa0939e70f",
"nodeType": "cm:folder",
"properties": {
"cm:title": "Data Dictionary",
"cm:description": "User managed definitions",
"app:icon": "space-icon-default"
},
"parentId": "03acc816-b42f-4d87-ab1f-4d4ae16e73ef"
}

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):

http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-/children?skipCo...

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.

"pagination": {
"count": 3,
"hasMoreItems": true,
"totalItems": 7,
"skipCount": 2,
"maxItems": 3
}

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):

http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-/children?where=...)

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):

http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-/children?where=...)

This will result in a single result as shown below.

{
"list": {
"pagination": {
"count": 1,
"hasMoreItems": false,
"totalItems": 1,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"createdAt": "2016-10-05T19:44:14.968+0000",
"isFolder": true,
"isFile": false,
"createdByUser": {
"id": "System",
"displayName": "System"
},
"modifiedAt": "2016-10-05T19:44:29.073+0000",
"modifiedByUser": {
"id": "System",
"displayName": "System"
},
"name": "Sites",
"id": "4f00d061-cdad-42b5-bfd6-8b0759a7fa7c",
"nodeType": "st:sites",
"parentId": "03acc816-b42f-4d87-ab1f-4d4ae16e73ef"
}
}
]
}
}

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):

http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-/children?orderB...

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:

http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/0be671ab-5fd9-4cc2-b93...

You've now learnt how to navigate the repository, in the next post we'll see how to create files and folders.

11 Comments
angelborroy
Expert

Let's assume I want to get folder properties by PATH.

Sites > test > TestFolder

Currently I can write following URL using CMIS API:

http://localhost:8080/alfresco/api/-default-/public/cmis/versions/1.1/browser/root/Sites/test/docume... 

Is there any equivalent path navigation by using REST API?

gavincornwell
Senior Member

Yes, there is, you can use the relativePath query parameter, you're example would be:

http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-?relativePath=Si...

angelborroy
Expert

Thanks for your quick response. However it does not work for me.

I'm receiving a 404 when using this call you gave me , probably because there is an intermediate "Company Home" node before "Sites" one:

http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root- 

{

  • entry:
    {
    • aspectNames:
      [
      • "cm:titled",
      • "cm:auditable",
      • "app:uifacets"
      ],
    • createdAt: "2017-02-14T14:02:39.817+0000",
    • isFolder: true,
    • isFile: false,
    • createdByUser:
      {
      • id: "System",
      • displayName: "System"
      },
    • modifiedAt: "2017-05-07T13:42:56.204+0000",
    • modifiedByUser:
      {
      • id: "admin",
      • displayName: "Administrator"
      },
    • name: "Company Home",
    • id: "0e0b3d83-d3dc-4ed4-bd3d-4f43cf6bfa63",
    • nodeType: "cm:folder",
    • properties:
      {
      • cm:title: "Company Home",
      • cm:description: "The company root space",
      • app:icon: "space-icon-default"
      }
    }

}

Any missing parameter from my part?

gavincornwell
Senior Member

That will teach me to try and go from memory, I didn't include the documentLibrary folder ;-)

This should work if you have a folder named TestFolder in a site called "test".

http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-?relativePath=Si...

Hope that helps!

angelborroy
Expert

Helps a ton!

I've recollected some comparative info at Alfresco, accessing folders by path via REST | Programming and So 

Hope also being useful for developers.

stefanguenst
Member II

Hi Gavin,

could you please give some example to the node API that i can filter 

get /nodes/{nodeId}/children

with "where" that only mimeType "video/mp4" will response ?

 

gavincornwell
Senior Member

Hi Stefan,

I'm afraid we don't currently support filtering by mimeType, the only supported options can be found in the API Explorer

I know it probably doesn't help you but mimeType is a supported orderBy clause, so you can do: http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?orderBy=... 

Gavin

stefanguenst
Member II

Hi Gavin,

thanks for quick response Smiley Happy 

I know this orderBy mimeType possibility but it will not help effective, so filtering must be badly made in frontend-layer 

Any plan to extend the Node-API in near future ? 

Stefan

gavincornwell
Senior Member

Hi Stefan,

Yes, we do plan to add that capability at some point, unfortunately it requires changes to the low level canned queries so it's not a trivial change.

I'm afraid I can't give a timeline but the fact someone has asked should bump it up the priority list a bit ;-)

Cheers,

Gavin

mwallach
Member II

Hi.

This is great, very helpful

I Think syntax is wrong for INCLUDESUBTYPES where=(nodeType='my:specialNodeType' INCLUDESUBTYPES) should be where=(nodeType='my:specialNodeType INCLUDESUBTYPES') 

Mike

gavincornwell
Senior Member

You're absolutely right, many thanks for highlighting Mike. I have updated the post to reflect.