Just before Christmas we looked though the collaboration APIs for nodes, after a longer than planned hiatus the series continues with a look at some of the collaboration APIs for sites.
Way back in part 1 we installed 5.2.b, it's now time to re-install so that we can take a look at some of the newer APIs in this and future posts. Download and install the latest Community release (5.2.f at the time of writing) and optionally install the latest API Explorer by copying the WAR file as "api-explorer.war" to <install-home>/tomcat/webapps.
As has become tradition this post is accompanied by a Postman collection, click the "Run in Postman" button below to import it into your client.
One of the new APIs to have been added since 5.2.b is the create person API, let's use that to create a test user by POSTing the following body to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people (1st request in the Postman collection).
{
"id": "test",
"firstName": "Test",
"lastName": "User",
"email": "test@alfresco.com",
"password": "test"
}
This will result in the response below:
{
"entry": {
"firstName": "Test",
"lastName": "User",
"emailNotificationsEnabled": true,
"company": {},
"id": "test",
"enabled": true,
"email": "test@alfresco.com"
}
}
As with all previous posts we'll use this user for all subsequent requests unless specified otherwise.
OK, let's start by using one of the new endpoints added in 5.2, arguably one of the most anticipated, the ability to create a site that can be used in Share!
To create a standard site with default configuration POST the body below to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/sites (2nd request in the Postman collection).
{
"id": "publicSite",
"title": "Public Site",
"description": "Public site created for blog post",
"visibility": "PUBLIC"
}
This will result in a response similar to the one below:
{
"entry": {
"role": "SiteManager",
"visibility": "PUBLIC",
"guid": "69a5a7b1-a338-4e11-8a61-115edd1190e6",
"description": "Public site created for blog post",
"id": "publicSite",
"preset": "site-dashboard",
"title": "Public Site"
}
}
Now we have created our site how do we add files to the Document Library? Each "page" in a site has a container in which it stores it's data, the Document Library is no different, we can use http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/sites/publicSite/containers/... endpoint (3rd request in the Postman collection) to GET the details (see response below), the id property provides the node identifier of the documentLibrary folder that we can then use in other APIs, refer back to part 3 for details on creating new nodes.
{
"entry": {
"id": "171f7d8a-09b0-413b-b41a-11e524833323",
"folderId": "documentLibrary"
}
}
Another new feature for 5.2 is the ability to update a site, to change the description of the site we just created PUT the body below to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/sites/publicSite (4th request in the Postman collection).
{
"description": "Public site created for blog post - part 8"
}
The response below shows that the site description has been updated.
{
"entry": {
"role": "SiteManager",
"visibility": "PUBLIC",
"guid": "69a5a7b1-a338-4e11-8a61-115edd1190e6",
"description": "Public site created for blog post - part 8",
"id": "publicSite",
"preset": "site-dashboard",
"title": "Public Site"
}
}
Although not demonstrated above it's also possible for a site manager to update the site's title and visibility properties, for example, to make a public site private.
Now let's turn our attention to site membership, to prepare for that we need to create a moderated site and create a second test user.
We create a moderated site in the same way we created the public site earlier except we pass "MODERATED" as the value for the visibility property as shown below (5th request in the Postman collection).
{
"id": "moderatedSite",
"title": "Moderated Site",
"description": "Moderated site created for blog post",
"visibility": "MODERATED"
}
The visibility property is an enum, the Alfresco API Explorer can be a great help here. Use the link or navigate to the POST /sites method and scroll down to the siteBodyCreate body parameter. Click the "Model" link on the right hand side to reveal the definition, this will show the allowed values for the enum.
Go ahead and create a second test user by POSTing the body below to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people (6th request in the Postman collection).
{
"id": "test2",
"firstName": "Test",
"lastName": "User2",
"password": "test2"
"email": "test2@alfresco.com"
}
We'll now use this new user to join the public site we created earlier and the moderated site we just created. The same endpoint is used to do both these actions http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people/test2/site-membership.... Join the public site by POSTing the body below (7th request in the Postman collection).
{
"id": "publicSite"
}
This will return a response similar to the one shown below:
{
"entry": {
"createdAt": "2017-02-24T09:52:09.052+0000",
"site": {
"role": "SiteConsumer",
"visibility": "PUBLIC",
"guid": "69a5a7b1-a338-4e11-8a61-115edd1190e6",
"description": "Public site created for blog post - part 8",
"id": "publicSite",
"preset": "site-dashboard",
"title": "Public Site"
},
"id": "publicSite"
}
}
As the site is public we are added immediately with the role of SiteConsumer, which can be seen in line 5.
Attempt to join the moderated site by POSTing the body below (8th request in the Postman collection).
{
"id": "moderatedSite",
"message": "I would like to join this site as it looks interesting"
}
This will return a response similar to the one below.
{
"entry": {
"createdAt": "2017-02-24T10:16:21.524+0000",
"site": {
"visibility": "MODERATED",
"guid": "46b6504d-27e9-4137-b680-fb0be986942d",
"description": "Moderated site created for blog post",
"id": "moderatedSite",
"preset": "site-dashboard",
"title": "Moderated Site"
},
"id": "moderatedSite",
"message": "I would like to join this site as it looks interesting"
}
}
The response is similar to the one we got when joining the public site with one notable exception, there is no role property, this is because you haven't actually joined the site yet, your request has been sent to the site managers for approval.
To check your pending site membership requests you can GET http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people/test2/site-membership... (9th request in the Postman collection). You can manage your site membership requests using the /people/test2/site-membership-requests/{siteId} endpoint, refer to the API Explorer for details.
Site managers can not currently accept or reject site invitations via the /sites API, this has to be done via the workflow API, I've added a story to our backlog to add this missing functionality.
Now we're a member of the public site let's see who else is. If you GET http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/sites/publicSite/members (10th request in the Postman collection) you'll get the following response.
{
"list": {
"pagination": {
"count": 2,
"hasMoreItems": false,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"role": "SiteManager",
"person": {
"firstName": "Test",
"lastName": "User",
"emailNotificationsEnabled": true,
"company": {
},
"id": "test",
"enabled": true,
"email": "test@alfresco.com"
},
"id": "test"
}
},
{
"entry": {
"role": "SiteConsumer",
"person": {
"firstName": "Test",
"lastName": "User2",
"emailNotificationsEnabled": true,
"company": {
},
"id": "test2",
"enabled": true,
"email": "test2@alfresco.com"
},
"id": "test2"
}
}
]
}
}
This shows that the "test" user is the site manager (lines 12 and 20) and the "test2" user is a site consumer (lines 29 and 37).
To see all the sites you are a member of the http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people/test2/sites endpoint can be used (11th request in the Postman collection), this will give the following response.
{
"list": {
"pagination": {
"count": 1,
"hasMoreItems": false,
"totalItems": 1,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"site": {
"role": "SiteConsumer",
"visibility": "PUBLIC",
"guid": "69a5a7b1-a338-4e11-8a61-115edd1190e6",
"description": "Public site created for blog post - part 8",
"id": "publicSite",
"preset": "site-dashboard",
"title": "Public Site"
},
"role": "SiteConsumer",
"guid": "69a5a7b1-a338-4e11-8a61-115edd1190e6",
"id": "publicSite"
}
}
]
}
}
As our request to join the moderated site has not been approved yet we are only a member of one site, the public site we joined earlier.
So how do you find sites to join?
To list all public and moderated sites in the system the http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/sites endpoint can be used (12th request in the Postman collection), this will return the following response.
{
"list": {
"pagination": {
"count": 3,
"hasMoreItems": false,
"totalItems": 3,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"visibility": "MODERATED",
"guid": "46b6504d-27e9-4137-b680-fb0be986942d",
"description": "Moderated site created for blog post",
"id": "moderatedSite",
"preset": "site-dashboard",
"title": "Moderated Site"
}
},
{
"entry": {
"role": "SiteConsumer",
"visibility": "PUBLIC",
"guid": "69a5a7b1-a338-4e11-8a61-115edd1190e6",
"description": "Public site created for blog post - part 8",
"id": "publicSite",
"preset": "site-dashboard",
"title": "Public Site"
}
},
{
"entry": {
"visibility": "PUBLIC",
"guid": "b4cff62a-664d-4d45-9302-98723eac1319",
"description": "This is a Sample Alfresco Team site.",
"id": "swsdp",
"preset": "site-dashboard",
"title": "Sample: Web Site Design Project"
}
}
]
}
}
If you are a member of any of the sites your role in that site is indicated (line 23). The other way to find sites is to search for them and there are a couple of ways to do that. You could use the new Search API which I'll be covering in the next post or you can use the Queries API. We'll also be covering the new Queries API in a future post so I'll just briefly mention it now.
The /queries/sites endpoint is "pre-canned" query for sites, you pass a single term as a query parameter. For example, calling http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/queries/sites?term=public will return a response similar to the one below (13th request in the Postman collection).
{
"list": {
"pagination": {
"count": 1,
"hasMoreItems": false,
"totalItems": 1,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"role": "SiteConsumer",
"visibility": "PUBLIC",
"guid": "69a5a7b1-a338-4e11-8a61-115edd1190e6",
"description": "Public site created for blog post - part 8",
"id": "publicSite",
"preset": "site-dashboard",
"title": "Public Site"
}
}
]
}
}
The last thing to cover in this section is how to leave a site you've previously joined. As you might expect a DELETE endpoint is used to do this. To leave the "publicSite" we joined earlier use http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/people/test2/sites/publicSit... (14th request in the Postman collection). A 204 response is returned if you successfully left the site.
For the last section of this post we're going to take a look at some of the other endpoints available to the site manager.
A manager of a site is able to add members with a specific role. To add "test2" as a member of the "publicSite" created earlier with the "SiteContributor" role we can POST the following body to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/sites/publicSite/members. Remember to switch your credentials back to the "test" user or use the 15th request in the Postman collection.
{
"id": "test2",
"role": "SiteContributor"
}Allowable values for the role property are SiteManager, SiteCollaborator, SiteContributor or SiteConsumer
Now we've added test2 to the site let's say we want to change their role to be a site manager, this can be accomplished by PUTing the following body to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/sites/publicSite/members/tes... (16th request in the Postman collection).
{
"role": "SiteManager"
}
Finally, to remove the "publicSite" site use a DELETE request against http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/sites/publicSite (last request in the Postman collection), you should receive a 204 status code.
We've covered a majority of the Sites API in this post but there is more so I'd encourage you to examine the API Explorer and experiment.
In the next instalment of the series we're going to take a look at the new queries and search APIs.
2 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.