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:
Explore the application of REST on Content Management
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.
The design goals of the HTTP API are:
Simple as possible to understand and consume
Minimum of client tooling
Support remote access (batching / transactions)
Support for multiple repository access
Keep in-line with up-and-coming de-facto REST standards such as Atom, OpenID, OpenSearch
Not brittle (i.e. upgrade service, add service etc)
100% Repository service coverage (eventually)
Cross-repository links (eventually)
Provide common interface to document mgt. and avm stores (for common functionality)
Allow for distributed Repository components (future â€“ i.e. add another content transformer at this network node)
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.
Alfresco Resources are represented as one the following entity types (primarily in Atom):
application/atom+xml : As specified in Atom syndication spec.
application/atom+xml;type=entry?? : As specified in Atom syndication spec.
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, ...
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
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)
application/atom+xml;type=entry?? : Atom Entry plus a) assoc type? b) from or to?
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.
Apply method directly to Resource (just require URL) â€“ no need to establish correct â€œserviceï¿½? url which might be difficult in distributed environment
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.
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.
GET /repository => Atom Service : Lists repository meta-data and available workspaces (i.e. Stores)