CMIS Protocol Bindings

In this final post of my Introduction to CMIS series, I will discuss the SOAP and REST protocol bindings for CMIS.  This post should provide an overview of how CMIS leverages SOAP and REST (particularly the AtomPub).  It is not a comprehensive reference on SOAP, REST or AtomPub.

Since the CMIS specifies the interaction between a client application and a CMIS compliant repository, there must be a standard over the wire interface that allows the client to exchange information with the repository.  CMIS compliant repositories must provide both a SOAP binding and a REST binding. CMIS compatible repositories must provide a service end point (or starting URL) for each of the bindings. The service URL and a (programmatic) understanding of the CMIS specification is all that a client needs to discover both the capabilities and content of a repository.

SOAP Binding

The SOAP binding maps directly to the CMIS domain model, services and method defined in Part 1 of the CMIS specification. For authentication, the repository should support WS-Security 1.1 for Username Token Profile 1.1 and has the option of supporting other authentication mechanisms.  A CMIS compliant repository may grant access to some or all of its services to unauthenticated clients.

For content tranfer the repository should support MTOM (SOAP Message Transmission Optimization Mechanism) and must accept base64 encoded content.

REST Binding

The REST binding is built on the ATOM Publishing protocol with CMIS specific extensions. A CMIS compatible client will discover the URIs that it needs to use to access the various services as it traverses the hierarchy.  As the client traverses through the repository, the relevant links will be presented to the client in the form of link, collection or uri template entries.  Each of the entries has markup (attributes or elements) that give the client an indication of what functionality the entry represents.  Each entry may represent one or more methods depending upon the HTTP method (GET, POST, PUT, DELETE) used to access the URL.  Any arguments that need to be passed to the repository will be use the argument names in the specification. For example when requesting that a response be paged, the client would  add something like: ?maxItems=50&skipCount=250

One very important note, if you are writing REST based CMIS client applications early on, you will be writing these applications without the benefit of an language based API.  You might be tempted to read the CMIS documentation of your favorite repository, figure out what URIs are used to access various methods and services and then hard code those URIs into your code.  That would not be a good idea as your code will only work on that repository and furthermore, may not work on subsequent releases of the repository.  Allow your client application to discover the proper URIs.  This way you can always count on your client working properly.

For authentication, any HTTP authentication scheme can be used.  In most cases basic authentication over TLS should be sufficient.  That said, there are many enterprise situations where other authentication schemes may be deployed.  The choice of authentication schemes can impact the ability of third party clients to operate on the repository.

In order to leverage ATOM Pub, CMIS needed to provide some namespace and media type extensions. The namespaces and media types used by CMIS are listed below.

Namespaces

The CMIS REST binding leverages the ATOM Pub namespaces and adds a couple of namespaces of its own.  The namespaces are listed below along with their commonly used prefixes.

• CMIS-Core
  Prefix: cmis
  http://docs.oasis-open.org/ns/cmis/core/200908/
• CMIS-RestAtom
  Prefix: cmisra
  http://docs.oasis-open.org/ns/cmis/restatom/200908/
• Atom
  Prefix: atom
  http://www.w3.org/2005/Atom
• AtomPub
  Prefix: app
  http://www.w3.org/2007/app

Media Types

The CMIS specification leverages some of the AtomPub media types and adds a few media types of its own.

CMIS Specific Media Types

• CMIS Query document
  application/cmisquery+xml
• CMIS AllowableActions document
  application/cmisallowableactions+xml
• Atom Document (Entry or Feed) with any CMIS Markup
  application/cmisatom+xml
• Atom Feed Document with CMIS Hierarchy extensions
  application/cmistree+xml
• CMIS ACL Document
  application/cmisacl+xml

Atom Media Types used by CMIS

• AtomPub Service
  application/atomsvc+xml
• Atom Entry
  application/atom+xml;type=entry
• Atom Feed
  application/atom+xml;type=feed

Summary

This should give you an idea of how CMIS leverages SOAP and REST to provide two over the wire options for client/repository interaction. If you are inclined to leverage SOAP, you can use the tools that you have to leverage the WSDL and build your applications.  If you are inclined to use REST, I would recommend reading Jeff Potts "Getting Started with CMIS" Tutorial.