The document summarizes updates to Alfresco's public API, including improvements to OAuth keys that allow longer refresh times, new favorites and site membership request APIs, and examples of calling the APIs. It also outlines the roadmap to merge the APIs into the next Alfresco release and add new API types and versions.

1. Tech Talk Live: Alfresco Public API
Update
April 3, 2013
Peter Monks, pmonks@alfresco.com
Greg Melahn, greg.melahn@alfresco.com

2. Agenda
• Overview
• What’s New
• Demo of the API in Action
• Roadmap
• Questions and Answers

3. Overview
Folder, file, content Networks, sites,
and metadata people, comments,
manipulation and tags, activities, …
search

4. Overview

5. Overview
• API URLs are structured:
– Tenant
– API scope
– API name
– API version
– Entity type*
https://api.alfresco.com/acme.com/public/alfresco/ versions/1/sites
* The notion of entity types doesn’t apply to CMIS.

6. Overview
• The entity type URL represents a
collection of all instances of that entity
– The collection may or may not be retrievable
via a GET
• Each instance of an entity can be
accessed via the collection URL with an Id
appended
.../acme.com/public/alfresco/versions/1/sites/mullet-gallery

7. Overview
• Entity types may also be nested
.../acme.com/public/alfresco/versions/1/sites/mullet-gallery/members
• The same rule about retrieving instances
by Id applies
.../acme.com/public/alfresco/versions/1/sites/mullet-gallery/
members/pmonks@alfresco.com

8. Overview
• Creating a new entity instance:
– POST to the collection URL
• Updating an entity instance:
– PUT to the instance URL
• Deleting an entity instance:
– DELETE against the instance URL
• These rules apply regardless of whether
it’s a top-level or nested collection

9. Overview
As of today:
• Only the “public” API scope is exposed
• API names are:
– alfresco
– CMIS
• Alfresco top-level entity types are:
– sites
– people
– tags
– nodes

10. Overview
• Over time the API will grow simply by
adding new entity types
• All new entity types will follow the same
rules
• The APIs (tenants, API scopes, API
names, API versions, entity types, etc.)
are fully discoverable
– No more relying on Alfresco version numbers!

11. What’s New
• oAuth Key Improvements
• Favorites API
• Site Membership Request API

12. oAuth Key Improvements
• Refresh keys last longer – now 28 Days
• Still secure, but more convenient!
• Users returning from leave won’t need to
re-authenticate
{
"access_token":"ad299019-c308-4588-84e6-fc76ee73fb35",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":" ",
"scope":"public_api"
}

13. Favorites API
• Favorites ( ) or Favourites ( )?
• A new Entity Type
• A new Collection under Person
– people/<personId>/favorites!
• Sites, Folders and Files can be made
Favorites
• Introduction of the WHERE parameter for
filtering of the favorites result set

14. Entity Type
Property Type JSON Type Description
targetGuid id string The guid of the
entity that is a
favorite
createdAt date time string The date and
time the object
was made a
favorite
target object object The object that
is a favorite.
This can be
site, a folder or
a file

15. API Patterns
• Getting favorites
– HTTP GET people/<personId>/favorites!
• Getting a favorite
– HTTP GET people/<personId>/favorites/
<targetGuid>!
• Adding a favorite
– HTTP POST people/<personId>/favorites!
• Removing a favorite
• HTTP DELETE people/<personId>/favorites/
<targetGuid>!
No PUT needed because the Favorite entity has no properties that can be modified by the
client.

16. Example – Getting Favorites
Request
HTTP GET people/fred.bloggs@example.com/favorites
Paging parameters (skipCount and maxItems) can be used to control response size.

17. Example – Getting Favorites
Response
HTTP 200 OK !
{
! ! !"list" : {!
! ! ! "pagination" : {!
! ! ! !"count" : 3,!
! ! ! !"hasMoreItems" : false,!
! ! ! !"skipCount" : 0,!
! ! ! !"maxItems" : 100!
},!
! ! ! "entries" : [!
! ! ! {!
"entry" : {
"targetGuid" : "8ac18731-601b-4bb4-be1a-cd5d252cce3f",
"createdAt" : "2012-07-20T21:46:09.659+0000",
"target": {
"site" : {!
"id" : "foo",!
"guid" : "8ac18731-601b-4bb4-be1a-cd5d252cce3f",!
! ! ! ! "title" : "The Foo Site",!
"visibility" : "PRIVATE",!
! ! ! ! "description" : "The Foo Site",!
! ! ! ! ! "role" : "SiteManager”!
! ! ! }!
! ! ! }!
! ! ! }
! ! }, … more entries (one per favorite)

18. Example – Getting a Favorite
Request
HTTP GET people/fred.bloggs@example.com/favorites/
8ac18731-601b-4bb4-be1a-cd5d252cce3f!
! ! !

19. Example – Getting a Favorite
Response
HTTP 200 OK!
! ! !{!
"entry" : {
"targetGuid" : "8ac18731-601b-4bb4-be1a-cd5d252cce3f",
"createdAt" : "2012-07-20T21:46:09.659+0000",
"target": {
"site" : {!
"id" : "foo",!
"guid" : "8ac18731-601b-4bb4-be1a-cd5d252cce3f",!
! ! ! "title" : "The Foo Site",!
"visibility" : "PRIVATE",!
! ! ! ! "description" : "The Foo Site",!
! ! ! ! !"role" : "SiteManager”!
! ! ! ! }!
! ! ! }!
! ! ! }
! ! }
Notice we return the role as a convenience to reduce the need for more requests later

20. Example – Adding a Favorite
Request
HTTP POST people/fred.bloggs@example.com/favorites!
{!
"target": {
"site" : { !
"guid" : "8ac18731-601b-4bb4-be1a-cd5d252cce3f"!
} !
}
}

21. Example – Adding a Favorite
Response
HTTP 201 Created !
! ! !{!
"entry" : {
"targetGuid" : "8ac18731-601b-4bb4-be1a-cd5d252cce3f",
"createdAt" : "2012-07-20T21:46:09.659+0000",
"target": {
"site" : {!
"id" : "foo",!
"guid" : "8ac18731-601b-4bb4-be1a-cd5d252cce3f",!
! ! ! "title" : "The Foo Site",!
"visibility" : "PRIVATE",!
! ! ! ! "description" : "The Foo Site",!
! ! ! ! "role" : "SiteManager”!
! ! ! ! }!
! ! }!
! ! }
! ! }

22. Example – Removing a Favorite
Request
HTTP DELETE people/fred.bloggs@example.com/
favorites/8ac18731-601b-4bb4-be1a-cd5d252cce3f!
!
Response
HTTP 204 No Content!
!

23. Introducing the where parameter
• Used to limit the response to only those
favorites meeting certain criteria
• Uses an SQL like predicate, EXISTS
• JSON pointer syntax used as values
– target/file
– target/folder
– target/site
• e.g. where=(EXISTS(target/file)
OR EXISTS(target/folder))
!

24. Site Membership Request API
• A new Entity Type
• A new Collection under Person
– people/<personId>/site-membership-
requests!
• Requests to join moderated sites go into the
approval workflow just as in the Share app
• Requests to join public sites are implicitly granted
• Requests to join private sites are just ignored
– and a 404 hides the existence of the private site
• You can only request to join a site in your own
network

25. Entity Type
Property Type JSON Description
Type
id id string The id of the site
site object object The site for which this is a
request
message string string A message from the requester
explaining why membership in
the site is being requested
(optional)
createdAt date time string The date and time the site
membership request was
made
modifiedAt date time string The date and time the site
membership request was
changed

26. API Patterns
• Getting a list of site membership requests
– HTTP GET people/<personId>/site-membership-
requests!
• Requesting to join a site
– HTTP POST people/<personId>/site-membership-
requests!
• Changing a request
– HTTP PUT people/<personId>/site-membership-
requests/<siteId>!
• Withdrawing a request
• HTTP DELETE people/<personId>/site-membership-
requests/<siteId>

27. Example – Getting a List of Site
Membership Requests
Request
HTTP GET people/fred.bloggs@example.com/
site-membership-requests!

28. Example – Getting a List of Site
Membership Requests
Response
HTTP 200 OK !
{
! ! !"list" : {!
! ! ! "pagination" : {!
! ! ! !"count" : 3,!
! ! ! !"hasMoreItems" : false,!
! ! ! !"skipCount" : 0,!
! ! ! !"maxItems" : 100!
! ! },!
"entries" : [!
{
! ! ! "entry": {
"id" : "the-secret-site",
"createdAt" : "2012-07-20T21:46:09.659+0000",
"modifiedAt" : "2012-07-20T21:46:09.659+0000",
"message" : "I am working on the secret project too!", !
"site" : {!
"id" : "the-secret-site",!
"guid" : "8ac18731-601b-4bb4-be1a-cd5d252cce3f",!
"title" : "The Company’s Secret Site",!
"visibility" : "MODERATED",!
"description" : "The Company’s Secret Site" !
}!
}!
}, … more entries (one per request)

29. Example – Requesting to Join a
Site
Request
HTTP POST people/fred.bloggs@example.com/
site-membership-requests!
!
{
"id" : "the-secret-site",
"message" : "I am working on the secret project too!"
}
!

30. Example – Requesting to Join a
Site
Response
HTTP 201 Created !
{
! ! ! "entry": {
"id" : "the-secret-site",
"createdAt" : "2012-07-20T21:46:09.659+0000",
"modifiedAt" : "2012-07-20T21:46:09.659+0000",
"message" : "I am working on the secret project”, !
"site" : {!
"id" : "the-secret-site",!
"guid" : "8ac18731-601b-4bb4-be1a-cd5d252cce3f",!
"title" : "The Company’s Secret Site",!
"visibility" : "MODERATED",!
"description" : "The Company’s Secret Site"
}!
}
}
!

31. Example – Changing a Request
to Join a Site
Request
HTTP PUT people/fred.bloggs@example.com/site-
membership-requests/the-secret-site!
!
{
"id" : "the-secret-site",
"message" : "I really need access!"
}
!

32. Example – Changing a Request
to Join a Site
Response
HTTP 200 OK!
{
! ! ! "entry": {
"id" : "the-secret-site",
"createdAt" : "2012-07-20T21:46:09.659+0000",
"modifiedAt" : "2013-04-03T16:41:11.659+0000",
"message" : “I really need access!", !
"site" : {!
"id" : "the-secret-site",!
"guid" : "8ac18731-601b-4bb4-be1a-cd5d252cce3f",!
"title" : "The Company’s Secret Site",!
"visibility" : "MODERATED",!
"description" : "The Company’s Secret Site"
}!
}
}
!

33. Example – Withdrawing a
Request to Join a Site
Request
HTTP DELETE people/fred.bloggs@example.com/
site-membership-requests/the-secret-site!
!
Request
HTTP 204 No Content!

34. The API in Action
• Demo

35. Roadmap
• Merge APIs into Alfresco Enterprise v4.2
• New API types:
– User Provisioning (SCIM)
– Workflow (Activiti)
• New API versions:
– CMIS v1.1
– Alfresco v2 (?)
• New Alfresco API entity types:
– renditions
– bulk-imports (?)

36. Roadmap
• Binary property support
• Projection & transclusion improvements
(“SELECT”)
• Restriction improvements (“WHERE”)
• Discoverability improvements
– In support of “executable documentation”

37. Try It Yourself
• Register for a Developer Key
– http://www.alfresco.com/develop
• Read the Documentation
– https://www.alfresco.com/cmis/browser?
id=workspace%3A//SpacesStore/
b09d212a-00c6-4ec3-9764-0eca67bb8529

38. Questions?