Intro to the Alfresco Public API

Intro to the Alfresco Public APIJeff PottsChief Community Officer

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

API Launch Partners

Folder, file, content and metadata manipulation and search

Networks, sites, people, comments, tags, activities, …

Getting Started

1. Understand OAuth22. Register your app3. Grab a client-side CMIS library

• Or an SDK if coding a mobile app

4. Start coding!

Step 1: Groking OAuth2

Defined in RFC-6749Secure 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)

OAuth2 & Alfresco

Used to secure the Alfresco APIOnly authentication mechanism

provided for APIs in Alfresco Cloud

Registering an App

ApplicationDeveloper

AlfrescoDeveloper Portal

Creates developer profile

Assigns an API key and secret for that app

Signs up on developer portal

Registers an application

AuthorizationApplication 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

Making API Calls

Calls APIs, passing the access token in the Authorization HTTP header

Identifies user from access token, executes API call

Application Alfresco

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

OAuth2 library can hide detailsSpring Socialhttp://www.springsource.org/spring-

social

Google OAuth2 Clienthttps

://developers.google.com/accounts/docs/OAuth2#libraries

Step 2: Register Your Apphttp://www.alfresco.com/develop

• Alfresco Cloud Account• Registered Developer Account

Add as many applications as you wantKey, secret, callback URL

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

REST client

http://youtu.be/5QS0CNsPJEY

Create, Find, & Comment

http://youtu.be/1ZtmoPdCKJI

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/

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

Top level entity types

sitespeopletagsnodesfavorites

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

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

Considerations

Rate limits• 5 requests/second, 10,000 requests/day

(Dev)• 50 requests/second, 100,000 requests/day

(Prod)

No limit on # of applicationsAlfresco Cloud users own their content>= OpenCMIS 0.8.0-SNAPSHOT>= cmislib 0.5.1dev

Roadmap

Merge APIs into Alfresco Enterprise v4.2New API types:

• User Provisioning (SCIM)• Workflow (Activiti)

New API versions:• CMIS v1.1• Alfresco v2 (?)

New Alfresco API entity types:• renditions• bulk-imports (?)

Roadmap

Binary property supportProjection & transclusion

improvements (“SELECT”)Restriction improvements (“WHERE”)Discoverability improvements

• In support of “executable documentation”

Getting HelpDocs: http://www.alfresco.com/developResources:

• Alfresco API forum• #alfresco on freenode IRC• Alfresco Technical Discussion Google Gro

up

Source Code:• Code from DevCon Session• Spring Social Alfresco Library• Peter’s Grails Example• Jeff’s Java Examples & Python Examples

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

The keys to one badass ECM platform are yours for the taking

http://www.alfresco.com/develophttp://www.flickr.com/photos/ph-stop/3101407532/