This document introduces the Alfresco Public API, which addresses limitations of Alfresco's existing API. The vision is for a single API that works across cloud and on-premise. The document explains how to get started with the API, including understanding OAuth2 authentication, registering an app, using a CMIS library, and making API calls. It provides an overview of entities and operations supported by the API.

1. Intro to the Alfresco Public
API
Jeff Potts
Chief Community Officer

2. Doesn’t Alfresco already have
an API?
Yes, but…
• Not really public (things change)
• Not versioned
• Not well documented
• Doesn’t work for cloud
The Alfresco Public API addresses these
limitations
Vision is to have a single API that works
across cloud and on-premise

3. API Launch Partners

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

7. Getting Started
1. Understand OAuth2
2. Register your app
3. Grab a client-side CMIS library
• Or an SDK if coding a mobile app
4. Start coding!

8. Step 1: Groking OAuth2
Defined in RFC-6749
Secure authentication
• 3rd party apps don’t ever see the user’s
password
Unambiguously identifies:
• API provider (e.g. Alfresco)
• Client application (e.g. your application)
• End-user (e.g. an Alfresco Cloud user)

9. OAuth2 & Alfresco
Used to secure the Alfresco API
Only authentication mechanism provided for
APIs in Alfresco Cloud

10. Registering an App
Application
Developer
Alfresco
Developer Portal
Creates developer
profile
Assigns an API key
and secret for that
app
Signs up on
developer portal
Registers an
application

11. Authorization
Application Alfresco End-User
Links to Alfresco
authorization page,
passing API key &
secret
Asks the user to
authorize the app
User authorizes the
app to access their
account
Redirects to your
app’s callback
URL, passing
authorization code
Exchanges the
authorization code
for an access token
Returns access and
refresh tokens
Securely persists
the access and
refresh token for
that user

12. Making API Calls
Calls APIs, passing
the access token in
the Authorization
HTTP header
Identifies user from
access token,
executes API call
Application Alfresco

13. Refresh Flow
Calls APIs, passing
the access token in
the Authorization
HTTP header
Returns 401 error,
indicating access
token has expired
Refreshes access
token, passing
refresh token
Returns new access
token
Application Alfresco

14. OAuth2 library can hide
details
Spring Social
http://www.springsource.org/spring-social
Google OAuth2 Client
https://developers.google.com/accounts/doc
s/OAuth2#libraries

15. Step 2: Register Your App
http://www.alfresco.com/develop
• Alfresco Cloud Account
• Registered Developer Account
Add as many applications as you want
Key, secret, callback URL

16. Step 3: CMIS Library
Apache Chemistry is the umbrella project for
all CMIS related projects at the ASF
• OpenCMIS (Java, client and server)
• cmislib (Python, client)
• phpclient (PHP, client)
• DotCMIS (.NET, client)
• ObjectiveCMIS (Objective-C)
Other client libraries exist

17. REST client
http://youtu.be/5QS0CNsPJEY

18. Create, Find, & Comment
http://youtu.be/1ZtmoPdCKJI

19. Alfresco API URLs
Structure:
• Tenant
• API scope
• API name
• API version
• Entity type
https://api.alfresco.com/
* The notion of entity types doesn’t apply to CMIS.
*
public/acme.com/ sitesalfresco/versions/1/

20. Entity type collections
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

21. Top level entity types
sites
people
tags
nodes
favorites

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

23. Create, update, & delete
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

24. Considerations
Rate limits
• 5 requests/second, 10,000 requests/day (Dev)
• 50 requests/second, 100,000 requests/day (Prod)
No limit on # of applications
Alfresco Cloud users own their content
>= OpenCMIS 0.8.0-SNAPSHOT
>= cmislib 0.5.1dev

25. 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 (?)

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

27. Getting Help
Docs: http://www.alfresco.com/develop
Resources:
• Alfresco API forum
• #alfresco on freenode IRC
• Alfresco Technical Discussion Google Group
Source Code:
• Code from DevCon Session
• Spring Social Alfresco Library
• Peter’s Grails Example
• Jeff’s Java Examples & Python Examples

28. Read the book!
Everything you need to
know about CMIS
1.0 & 1.1
Lots of Groovy and
Java examples
Also covers Python,
Android, & iOS
Now on MEAP!
37%-off: 12cmisal

29. The keys to one badass ECM platform are yours for
the taking
http://www.alfresco.com/develop
http://www.flickr.com/photos/ph-stop/3101407532/