You are here

Things to know before you start

Things that you should know before you start using the ReST API.

Introduction

The Alfresco ReST API endpoints share many features, such as the format for collection responses, how to sort and order responses, how to limit results, how to request optional information, etc.

So it makes sense to know about these features before you start using the API, as sometimes documentation might not cover all these common features, and you would then have to resort to the API Explorer reference.

The API Explorer is your source of truth

The reference documentation for the Alfresco ReST API is available in what is referred to as the API Explorer application. This application is available for each version of ACS.

If you are confused about what API endpoints that are supported for a specific version of ACS, then install the associated API Explorer and check if the API endpoint is available. If you are wondering about specific API endpoint details, and you cannot find any information about it anywhere, consult the API Explorer.

You can find more information about the API Explorer on this page, which also has information on how to install it for your specific version of ACS.

If you want to know what the API Explorer looks like right now, then have a look at the online version at https://api-explorer.alfresco.com/api-explorer (note that this API Explorer always shows the API for the latest version of ACS).

Finding out if an API endpoint is supported in a specific ACS version

The majority of the API endpoints have information in the Open API specification (i.e. Swagger docs) about what version of ACS that is required (i.e. in the API Explorer).

This version information is usually available in the beginning of the API endpoint description, as in the following screenshot:

Note that an API endpoint can be supported from a specific patch version of ACS, such as in the following screenshot:

If you are running an earlier version of ACS, which doesn't support the API endpoint, then you would need to upgrade your ACS installation before starting to use this endpoint.

Tickets

It's common to use HTTP basic authentication when trying out the ReST API.

However, the basic auth mechanism provides no confidentiality protection for the transmitted credentials. They are merely encoded with Base64 in transit, but not encrypted or hashed in any way. Therefore, basic Authentication is typically used in conjunction with HTTPS to provide confidentiality.

Alfresco ReST API also provides another way of authenticating with the repository. 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:

{
  "userId": "admin",
  "password": "admin"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

The response provides the ticket in the id property:

{
  "entry": {
    "id": "TICKET_ed4981b4bbb15fc2713f7caaffd23982d0dd4e5c",
    "userId": "admin"
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

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.

How to get a ticket and how to use it is explained here in the ReST API user guide.

Limiting result items

By default the API will return a maximum of 100 result items in any one request, this can be controlled via the maxItems query parameter.

The http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?maxItems=5 request shows how you can limit the number of result items to five.

This query parameter is supported across all collection endpoints.

Skipping result items

By default the API will return result items starting from the beginning, it's possible to skip any number of result items using the skipCount query parameter. This is typically used for implementing paging or infinite scrolling in clients.

The http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?skipCount=2 request shows how you can skip the first two result items.

This query parameter is supported across all collection endpoints.

Ordering result items

All collection endpoints (those returning a list of result items) will have a default sort order. It's possible to change the sort order on some endpoints via the orderBy query parameter.

The http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?orderBy=sizeInBytes DESC request shows how you can order the nodes in your home folder by the size of the content, starting with the largest item.

The direction of the sorting can be controlled by the DESC (descending) and ASC (ascending) keywords.

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 that can be used.

Filtering result items

Sometimes only a subset of the response items are 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 http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?where=(isFile=true) request 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.

Requesting optional item information

We have taken what we're calling a "performance first" approach with the API. This means that each endpoint, by default, only returns the item information that is efficient to retrieve.

If additional processing is required on the server side to obtain the item information, then it's made available via the include query parameter.

The http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?include=properties,aspectNames request shows how you can also include the properties and aspects for each node in your home folder when listing its children.

As with the orderBy and where parameters, the include parameter is specific to the endpoint so you'll need to consult the API Explorer to see what extra item information is available.

Limiting the item information

Sometimes bandwidth is a major consideration, such as when building a mobile client.

To cater for this scenario the API allows you to control the amount of item data sent over the wire via the fields query parameter.

The http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?fields=id,name request shows how you can limit the item 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. It's then possible to use the fields=id,name&include=aspectNames query parameter string. No need to specify the aspectName value again in the fields parameter.

The fields parameter is supported universally across all endpoints.

Person id 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 http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people/-me- request shows how this can be used to retrieve the profile information of the currently authenticated user.

Well known node id aliases

There are several endpoints across the API that expect a node id as part of the URL, this is OK if the client knows the node id, but there are some scenarios where it might not be known, for example when starting to navigate the folder hierarchy.

For this scenario the API supports the following node id aliases:

  • -root-: corresponds to the node id for the /Company Home folder.
  • -shared-: corresponds to the node id for the /Company Home/Shared folder.
  • -my-: corresponds to the node id for the current user's home folder (i.e. /Company Home/User Homes/{userid}).

The http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-/children request shows how you can list the contents (children) of the /Company Home folder without knowing its node id.

Creating multiple entities (items)

Supporting batch operations, such as 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 http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children request 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.

Including the source entity for a collection

When returning a relationship collection for 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 http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children?includeSource=true request shows how you'd include details of the user's home folder when listing its 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 http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/sites/swsdp/members?includeSource=true URL.

The includeSource parameter is supported for all endpoints that include an entity and a relationship collection.

Sending feedback to the Alfresco documentation team

You don't appear to have JavaScript enabled in your browser. With JavaScript enabled, you can provide feedback to us using our simple form. Here are some instructions on how to enable JavaScript in your web browser.