Web Services Design Guidelines

Document created by resplin Employee on Jun 6, 2015
Version 1Show Document
  • View in full screen mode

{{Obsolete}}

Please note that this API has been superceded by CMIS (specifically, the CMIS SOAP binding).  It's use is no longer recommended. This functionality was removed from Alfresco in 5.0.b.

Back to Alfresco Content Management Web Services.




This page covers issues and choices that occur during the development of Alfresco's Web Services.

Please feel free to comment or make suggestions as to how we can improve our implementation.


Compatibility between Web Service releases


TODO: How to support versioning of services?

TODO: Policy for backward/forward compatibility


Encoding


All web services will support Document/Literal (or perhaps Document wrapped?) encoding.


Security


We're investigating the use of WS-Security. However, our past experience has caused us to back away, purely, because of the lack of implementation support. Today, of course, could be a different story.  Anyone have experience of WS-Security who'd like to contribute?

So, for now, you'll see a rather simple Authentication interface for establishing a session.  Many other current APIs seem to take this approach and pass the notion of a ticket via the SOAP header for subsequent service calls.  In the meantime, we'll continue to investigate WS-Security.

All Web Services will comply with the access control defined in the Repository and as such will not provide visibility to data or manipulation of data that is outside the permissions of the user interacting with the service.

Alfresco's implementation will simply hook into the existing Repository support for authentication.

Update:
With the release of WSS4J v1.0, we have now integrated WSS4J into our implementation stack and thus provide WS-Security support.


Error Handling


TODO: define


Transactions


Again, we'd like to fit with wider reaching standards, allowing full integration possibilities such as enterprise wide business processes. So, we're investigating these areas to see what's available and their implications. Anyone have experience of WS-Transaction or equivalents who'd like to contribute?

In the mean-time, each web service call will operate in its own transaction, either succeeding or failing as a whole. As such, along with the remote nature of web services, operations will be designed to allow batch processing where necessary to reduce roundtrips and control of atomicity.


Content Support


We're also investigating capabilities for handling content within Web Services such as:


  • SOAP with Attachments
  • XOP

Anyone have any experience of these or alternatives?


Resource Identification


TODO: This area to be worked on...

Content resources (entities, nodes, objects - choose your preferred name) are referred to throughout the Web Services. To identify a resource we're intending to expose the notions we already have in the Repository. These are:


  • Resource Identifier
    • UUID
    • Path (absolute or relative to the UUID)

To assist in locating a resource, the notion of a Store (again, name to be determined) will be exposed. For some background refer to Node Handles and Store Protocols.

The store is identified by a scheme and address.  Schemes include:


  • workspace? - a store where live content is held
  • version - a store where archived / snapshot content is held
  • search - a virtual search scope
  • http?? - a web accessible content store

The address is a scheme specific identifer for identifying the specific store.

Not all schemes are supported by all web service operations.

A full resource reference consists of both store and resource identifier.


Predicate


There are occasions when a web service operation operates against a collection of resources.  It is the intention to provide a standard means of defining the collection of resources via the notion of a Predicate (note: terminology to be confirmed) allowing any one of following:


  • Resource Identifier (UUID, Path)
  • Resource Identifier Collection
  • Query

Attachments

    Outcomes