Alfresco REST API Proposal

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

REST APIWeb ScriptsSocial ComputingOverview
Back to HTTP API.

NOTE:

This document presents ideas & thoughts for an Alfresco RESTful Web Services API for Content Management.

The content herein does not necessarily reflect current Alfresco product vision or development plan.

Table of Contents

• 1 Proposal: Alfresco RESTful Web Services API


• 2 API Goals


• 3 Constructs


• 4 Representations
  
  
  
  • 4.1 Atom Feed
  
  
  • 4.2 Atom Entry
  
  
  • 4.3 Atom Service
  
  
  • 4.4 OpenSearch Description
  
  
  • 4.5 OpenSearch Atom Feed
  
  
  • 4.6 Alfresco Saved Search
  
  
  • 4.7 Alfresco Item
  
  
  • 4.8 Alfresco Association
  
  
  • 4.9 Alfresco Lock
  
  
  • 4.10 Alfresco Checkin Note
  
  


• 5 Alternative Representation: JSON


• 6 Alternative Representation: HTML


• 7 Custom HTTP Methods
  
  
  
  • 7.1 ITEMLOCK
  
  
  • 7.2 ITEMUNLOCK
  
  
  • 7.3 ITEMCHECKOUT
  
  
  • 7.4 ITEMCHECKIN
  
  
  • 7.5 SETPROP (update individual properties)
  
  


• 8 Resources
  
  
  
  • 8.1 Repository
  
  
  • 8.2 Search Engine Registry
  
  
  • 8.3 Keyword Search Description
  
  
  • 8.4 SQL Search Description
  
  
  • 8.5 Alfresco Lucene Search Description
  
  
  • 8.6 Keyword Search Results
  
  

Proposal: Alfresco RESTful Web Services API

History:

27th March 07 - Initial thoughts & ideas

13th June 07 - Reformat and publish to Alfresco WIKI

This document presents ideas & thoughts for an Alfresco RESTful Web Services API for Content Management.

Objectives of this work are to:

1. Explore the application of REST on Content Management
   
2. Collect feedback on approach & desire
   

We're hosting this document on the Alfresco Wiki to encourage feedback and collaborative development from anyone who may have an interest in Content Management, RESTful approaches in general, or a combination of both. As such, this document is 'living' and changing for the foreseeable future as ideas stabilize, discussion takes place etc.  Please note: the content herein does not necessarily reflect current Alfresco product vision or development plan.

Initially, a limited scope of services have been investigated. This is to minimise up-front work to get the ball rolling.

A simple test case has been used to kick-start the research; a federated search & update application which allows a single search across multiple content repositories, with view and update of items returned in search results. Alfresco Web Scripts will be used to enable rapid prototyping of ideas.

API Goals

The design goals of the HTTP API are:

1. Simple as possible to understand and consume
   
2. Minimum of client tooling
   
3. Support remote access (batching / transactions)
   
4. Support for multiple repository access
   
5. Keep in-line with up-and-coming de-facto REST standards such as Atom, OpenID, OpenSearch
   
6. Not brittle (i.e. upgrade service, add service etc)
   
7. 100% Repository service coverage (eventually)
   
8. Cross-repository links (eventually)
   
9. Provide common interface to document mgt. and avm stores (for common functionality)
   
10. Allow for API variants for client specific bindings (e.g. Browser client-side Javascript)
    
11. Allow for distributed Repository components (future – i.e. add another content transformer at this network node)
    

Although the HTTP API may be used directly by clients, it is also envisioned that a client API will be provided for  commonly used languages (e.g. Java/JCR, PHP, Javascript).  The definition of the client API is deferred for now.  However, it should be noted the same client API could be used for in-process Repository access too.

Constructs

The API is focused on a set of Alfresco “Resources�?.  Resources include repository data such as folders & files, as well as services such as a Search Engine.

Each resource is given a URL – an identifier.

Resource representations have been modeled on Atom & Atom Publishing Protocol (APP).  In most cases, collections are represented as an Atom feed, and items are represented as Atom entries.  The extension mechanism of Atom is used to support Alfresco specific meta-data.

Resources support methods – the primary ones being GET, PUT, POST & DELETE.  Not all methods are supported by all resources.  After much deliberation, custom methods outside of the HTTP specification are introduced for some Alfresco capabilities.  This is an area we definitely want feedback on.

Interaction patterns for creating, updating and deleting resources have also been borrowed from Atom Publishing Protocol.

Atom may not be the only representation.  Via Web Scripts we could also provide alternative representations such as JSON (both on request and response). A transformation could be provided for Atom, JSON and RSS switching.

The constructs described are not unknown – see Google Data API.

Representations

Alfresco Resources are represented as one the following entity types (primarily in Atom):

Atom Feed

application/atom+xml : As specified in Atom syndication spec.

Atom Entry

application/atom+xml;type=entry?? : As specified in Atom syndication spec.

Atom Service

application/atomserv+xml : As specified in Atom publishing spec plus a) repository meta data (e.g. Version). Note: Atom workspace => Alfresco store, Atom collections => Alfresco root container, locks, ...

OpenSearch Description

application/opensearchdescription+xml : As specified in OpenSearch spec.

OpenSearch Atom Feed

application/atom+xml : Atom syndication extensions as specified in Open Search spec.

Alfresco Saved Search

application/opensearchdescription+xml : OpenSearch Description plus a) query language b) query statement

Alfresco Item

application/atom+xml;type=entry?? : Atom Entry plus a) type b) aspects c) property values d) permissions e) locks . Note: link rel=�?alternate�? or “enclosure�? is pointer to content, link rel=�?edit�? may apply to self or copy (if checked-out)

Alfresco Association

application/atom+xml;type=entry?? : Atom Entry plus a) assoc type? b) from or to?

Alfresco Lock

application/atom+xml;type=entry?? : Atom Entry plus a) lock type (read, write, checkout) b) owner c) include children d) time to expire (optional) e) item (rel=�?locked item�?)

Alfresco Checkin Note

application/atom+xml;type=entry?? : Atom Entry plus a) keep locked b) checkin properties c) lock??

Alternative Representation: JSON

TODO: Mapping between Atom and JSON?

Alternative Representation: HTML

This is an interesting direction.  Essentially, this provides a “visual�? api.  The URIs remain the same, but the results are rendered in a form for human consumption.  Navigation is a case of issuing further API URIs – links within HTML.  Forms could  be provided for creates and updates.  Very useful for learning, testing and debugging the API.  Could also become an generic Repository Browser, but with updates, and for all Repository services.

Custom HTTP Methods

The following custom HTTP methods are provided for performing “advanced�? Resource operations.  Actually, WebDAV has similar.  Alternative approaches are listed below. 

Why?

1. Apply method directly to Resource (just require URL) – no need to establish correct “service�? url which might be difficult in distributed environment 
   
2. Apply method to many different kinds of Resource including collections e.g. Search results 
   

For those clients or environments which lock down HTTP methods, it is envisioned that they can be tunneled through POST by adding a header such as X-Method-Override.  See Web Script Method Tunneling.

ITEMLOCK

• Representation: Alfresco Lock
  
• Status: 201 Content location: Alfresco Lock
  

ITEMUNLOCK

• Representation: Alfresco Lock??
  
• 200??
  

ITEMCHECKOUT

• Representation: Alfresco Lock
  
• Status: 201 Content location: Alfresco Lock
  

ITEMCHECKIN

• Representation: Alfresco Checkin Note
  
• Status: 200 Alfresco Lock
  

SETPROP (update individual properties)

TBD

Resources

The API exposes the following Resources.  An example URI is given to assist visualization of the API, although the syntax is not important (only for easing human understanding / consumption).

Some Resources may be provisioned by both Document Mgt. & WCM stores.  The representation of such Resources is consistent across both.  Where possible, the supported methods are also consistent, however, some may not be supported, but that should be kept to a minimum.  The example URIs are driven by a Document Mgt store.  Alternative syntax may be used for WCM.

Repository

GET /repository => Atom Service : Lists repository meta-data and available workspaces (i.e. Stores)

Search Engine Registry

GET /search/engines => Atom Feed (of Atom Entry) : List registered search engines

Keyword Search Description

GET /search/keyword/description => OpenSearch Description : Get Keyword search description

SQL Search Description

GET /search/sql/description => OpenSearch Description : Get SQL search engine description

Alfresco Lucene Search Description

GET /search/lucene/description => OpenSearch Description : Get lucene search engine description

Keyword Search Results

GET /search/keyword => OpenSearch Atom Feed : Perform “google�? like search (Repository wide)

ITEMLOCK /search/keyword