Web Services Design Guidelines

[resplin]

{{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.

Table of Contents

• 1 Compatibility between Web Service releases


• 2 Encoding


• 3 Security


• 4 Error Handling


• 5 Transactions


• 6 Content Support


• 7 Resource Identification
  
  
  
  • 7.1 Predicate
  
  

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