v1 REST API - Part 10 - People

[gavincornwell]

In the last post we looked at the queries and search APIs, today we're going to look at the people API. A couple of the endpoints have been available since 4.2 and we've added a few new ones in the 5.2 release.

To keep with tradition this post has a Postman collection you can use to follow along, click the "Run in Postman" button below to import it into your client.

Let's start by creating a new person using one of the new endpoints added in the 5.2 release. We can POST the body below to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people (1st request in the Postman collection) to create a person with a username (id) of "jdoe". Any of the properties defined for the out-of-the-box cmerson type can be provided, for full details please refer to the API Explorer.

{
  "id": "jdoe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "password": "jdoe",
  "skypeId": "johndoe_skype",
  "jobTitle": "Software Engineer"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Sending the request above results in the following response:

{
  "entry": {
    "firstName": "John",
    "lastName": "Doe",
    "skypeId": "johndoe_skype",
    "jobTitle": "Software Engineer",
    "emailNotificationsEnabled": true,
    "company": {},
    "id": "jdoe",
    "enabled": true,
    "email": "john.doe@example.com"
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Some customers extend the out-of-the-box cmerson object so we have added support for custom properties too, for example to create a person with a custom property called mycompany:employeeId the following body could be used (presuming the property has been defined in the content model):

{
  "id": "jdoe",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "password": "jdoe",
  "skypeId": "janedoe_skype",
  "jobTitle": "Software Engineer",
  "properties": {
    "mycompany:employeeId": "abc-123"
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Another capability added in 5.2 is the ability to retrieve a list of people in the repository by using http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people (2nd request in the Postman collection) resulting in a response similar to the one below, which shows the person we just created.

{
  "list": {
    "pagination": {
      "count": 8,
      "hasMoreItems": false,
      "totalItems": 8,
      "skipCount": 0,
      "maxItems": 100
    },
    "entries": [
      {
        "entry": {
          "lastName": "Beecher",
          "userStatus": "Helping to design the look and feel of the new web site",
          "jobTitle": "Graphic Designer",
          "statusUpdatedAt": "2011-02-15T20:20:13.432+0000",
          "mobile": "0112211001100",
          "emailNotificationsEnabled": true,
          "description": "Alice is a demo user for the sample Alfresco Team site.",
          "telephone": "0112211001100",
          "enabled": false,
          "firstName": "Alice",
          "skypeId": "abeecher",
          "avatarId": "198500fc-1e99-4f5f-8926-248cea433366",
          "location": "Tilbury, UK",
          "company": {
            "organization": "Moresby, Garland and Wedge",
            "address1": "200 Butterwick Street",
            "address2": "Tilbury",
            "address3": "UK",
            "postcode": "ALF1 SAM1"
          },
          "id": "abeecher",
          "email": "abeecher@example.com"
        }
      },
      {
        "entry": {
          "firstName": "John",
          "lastName": "Doe",
          "skypeId": "johndoe_skype",
          "jobTitle": "Software Engineer",
          "emailNotificationsEnabled": true,
          "company": {},
          "id": "jdoe",
          "enabled": true,
          "email": "john.doe@example.com"
        }
      },
      ...
    ]
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

You may recall way back in part 2 when we discussed the /nodes API, the properties and aspect names are not present by default but can be included via the include query parameter, the same holds true here as well. If you want to see any custom properties or aspects applied you can add include=properties,aspectNames to the URL. The results can also be sorted by id (username), firstName and lastName.

Unfortunately, we ran out of time in the 5.2 release to add filtering capabilities to this endpoint, however, as discussed in the last post, the /queries/people endpoint (3rd request in the Postman collection) or the /search endpoint can be used to look for people and achieve the same thing.

To retrieve the full details of the person we created earlier we can use http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people/jdoe which returns the following response (4th request in the Postman collection):

{
  "entry": {
    "firstName": "John",
    "lastName": "Doe",
    "skypeId": "johndoe_skype",
    "jobTitle": "Software Engineer",
    "emailNotificationsEnabled": true,
    "company": {},
    "id": "jdoe",
    "enabled": true,
    "email": "john.doe@example.com"
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

It's also possible to update the details of a person (non administrator users can only update their own details for obvious reasons). The example below shows how we can update the details of the person we created earlier by PUTting the following body to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people/jdoe (5th request in the Postman collection):

{
  "firstName": "Johnathon",
  "mobile": "07000 123456"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Using the same endpoint it's also possible to change a person's password. For security reasons you can only change your own password (unless you're an administrator) and when you do you have to provide the old password together with the new password. The example below (6th request in the Postman collection) changes the password of the person we created earlier to "my-new-password":

{
  "oldPassword": "jdoe",
  "password": "my-new-password"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

The last capability of the people API we're going to cover today is the ability to disable and enable people, this is obviously something only administrators can do. You may have noticed the enabled flag for each person, this can be toggled to set the state of the person. It's also possible to create a person in the disabled state by setting the enabled property to false when the person is created.

The example below demonstrates how we can disable the person we created earlier. Again, we use PUT against http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people/jdoe to achieve this (7th request in the Postman collection):

{
  "enabled": false
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Now try and make a request using "jdoe" (remember to update the credentials to use the newer password), you'll get a 401 error as disabled users are locked out of the repository.

At this time there is no way to remove a person from the system via the v1 REST API, there are several nuances that need further discussion, once these discussions have concluded you can expect to see this capability added to a future release.

That concludes our coverage of the people API, I hope you'll join me again next time when we look at the trashcan (deleted nodes) API.