Extend SharePoint to the Cloud with MashPoint REST API

"May you live in interesting times."

SharePoint is certainly approaching an interesting period.  Microsoft is already providing SharePoint Online as a service that companies can use today, and in the announcement of the Azure Services Platform, SharePoint Services is prominently featured among the planned cloud-based service offerings.    One of the key components of Azure is that you can access the cloud service using the REST type interface.

What is REST?

Representational state transfer (REST) is a style of implementing network architecture that adheres to several important principles:

• Give everything an ID (or URI)
• Link things together
• Use standard methods
• Resources with multiple representations
• Stateless communication

In our context, REST is implemented as a Web service using the existing HTTP infrastructure.  HTTP gives each resource a unique ID using URI, what can be operated on with the standard verbs (GET, POST, DELETE and PUT) that can return data in a standard format such as XML, XHTML or vCard.

Why Build REST services for SharePoint?

Whether you are for or against REST API, most people will agree that the REST type API is very suitable for accessing data that can be thought of as "resources."  SharePoint fits the model well.  Think of List, Document Library, Audiences, Web Part, etc. as addressable resources that you can access using the standard URI with the supported method that allows for CRUD (Create, Read, Update and Delete) operations.

With its representation of data, the REST framework provides a much easier way for SharePoint to be in a larger SOA environment.  The ability to use SharePoint data to mash together multiple applications, whether they are inside or outside of the firewall, will give your system a taste of what the cloud computing model will be like in the near future.

If nothing else, having a clean URL alone might be incentive enough:

• http://sp/mashpoint/1/Lists/1/Items/2  - Read an item in a list
• http://sp/mashpoint/1/Lists/1/Permissions - Read all permission levels of this list
• http://sp/mashpoint/1/Lists/1/Fields  - Read all fields in this list
• http://sp/mashpoint/1/Lists/5/Views - Display all available views of the lists

What is MashPoint REST Services?

Bamboo MashPoint REST API (beta 1) is a REST-based remote interface to the data in MashPoint and SharePoint.  At its core, the MashPoint REST API is a framework for getting data in and out of SharePoint using the standard HTTP-based, REST-style system, in which data is moved around as representations of resources via HTTP methods.  A consistent number of resources and representations keeps the interface simple, while maintaining maximum flexibility and power as the standard SP Object Model.

Some of the distinct features of the MashPoint REST API are:

• Automatic discovery of SharePoint resources. The entire SharePoint object model can be accessed as REST endpoints.
• Legacy and LOB business data can be accessed via the MashPoint back-end.
• Support multiple representation data types: XHTML, Json, iCalendar and vCard.
• SharePoint can now participate in a wider SOA architecture.

MashPoint REST Resource Presentation Format

Out of the box, MashPoint REST will support the following representations for a resource: 

1. XHTML (text/xhtml): For browsing and discovery, can also be used for API since we will try to generate semantic markup.
2. ATOM (application/atom+xml ): Defaults to ADO.NET Data Services (Former Astoria) payload format, can be switched to GData Google base.
3. JSON (application/json): JSON (This is for RIA developed in JavaScript, since it's returning data in "native" java script format).
4. iCalendar (text/calendar): Sample implementation for SharePoint Events lists
5. vCard (text/x-vcard): Sample implementation for Contacts lists and lists with the Contacts ContentType

Examples of how you can switch between presentations are:

All resources:

• http://spserver/mashpoint/1/
• http://spserver/mashpoint/1/$atom$/
• http://spserver/mashpoint/1/$json$/

Events list:

• http://spserver/mashpoint/1/Lists/Calendar
• http://spserver/mashpoint/1/$atom$/Lists/Calendar
• http://spserver/mashpoint/1/$json$/Lists/Calendar
• http://spserver/mashpoint/1/$ical$/Lists/Calendar (iCalendar)

Contacts list (or lists with the Contacts ContentType applied)

• http://spserver/mashpoint/1/Lists/Contacts
• http://spserver/mashpoint/1/$atom$/Lists/Contacts
• http://spserver/mashpoint/1/$json$/Lists/Contacts
• http://spserver/mashpoint/1/$vcard$/Lists/Contacts (vCard)

MashPoint REST current limitations and roadmap

This beta release of MashPoint REST supports all possible resources and representations, but with READ only method.   Forthcoming releases will add support for additional methods, and other representations such as Atom.  You can expect the following updates and articles in the near future:

1. Accessing the SharePoint object model - Showing iCalendar and vCard use cases.
2. MashPoint REST Security - How is this secure?
3. MashPoint Extensibility - How can you extend the URI space?

Sometimes the best way to understand REST is to just download the Bamboo REST installer, and get some hands on experience, browsing through SharePoint objects using just a browser and standard applications to view the data. You do not need to install MashPoint to use the REST API to access SharePoint resources.

For more information on REST, you may wish to refer to the following recommended articles:

• Ryan Tomayko: How I Explained REST to my Wife
• Stefan Tilkov: A Brief Introduction to REST
• Joel Oleson: Great Move SharePoint and Windows Cloud OS "Windows Azure"

For more information:

• Download MashPoint REST API
• Discuss MashPoint REST API
• Read additional MashPoint articles