HttpCode

Some of the major web 2.0 sites like facebook and twitter are providing REST based API’s to interact with their services, if your not familiar with Representational State Transfer (REST), then now might be the perfect time for you to come up to speed because it seems that Microsoft is planning on incorporating more REST features in .NET 4, we already have some REST support in the current generation of tools.

The basic idea of REST is to use the existing infrastructure that the web already provides, we have HTTP verbs such as GET, POST, DELETE and PUT, which map pretty well to the CRUD model we deal with often. The web provides us with a simple error handling model, we all understand 404, 501 and 403 error codes (file not found, server error, unauthorised access). The final building block is the URL itself, we can create descriptive URL’s such that any user can infer it’s intent just by looking at it, while some may disagree with my summation, I think all of these elements together define what REST is.

If we contrast all of this with the world of SOAP and webservices, we soon realise that the webservices/SOAP model has been over-engineered. Do we really need to re-invent error codes and the calling conventions that already sit on top of the web, do we need all this SOAP overhead, one end-point for a raft of operations? Of course there will still be a place for traditional webservices, I’m not saying they don’t work or are going away, they clearly work and will be around for a while.

The webforms model of ASP.NET hasn’t really made it easy to create REST services, it was never really designed for it, however the ASP.NET framework has made developing REST’ful services a lot easier.

The first feature that the MVC framework offers is the flexibility of offering a URL routing engine, so that it is possible to easily create nice URL’s, but more than that, the way MVC uses the convention of {controller}/{action}/{parameter} you end up with code that without much effort becomes very REST like.

The second feature that MVC offers is the way each action on a controller returns an ActionResult, the framework provides inherited result classes such as the JsonResult and ContentResult, in effect the one action can return multiple payloads of data (in this case either a JSON view or an XML view). While not strictly fitting to the REST definition, most modern REST API’s return data in a format that is most easiest to work with which is increasing becoming JSON for AJAX/Mashable operations.

With this background we can now focus our attention on SharePoint, currently there are two ways to work with the data stored:

• Web services
• Object Model

I’ve already touched on what the limitations of the web services are, the SharePoint object model really only concerns us if our code is working inside SharePoint (i.e. on the same machine/s as SharePoint).

The Benefits to SharePoint of a REST API

• Enterprise mash-ability – the web is becoming more and more useful, one reason is that its now easier to mash together applications, look at any application that makes use of virtual earth or Google earth, flickr, twitter, live services etc. Imagine having this flexibility in your organisation, if your organisation has really embraced SharePoint then most likely it contains data that could be mashed into other systems, this REST framework is about exposing that data more easily.
• It still fits with an organisations Service Oriented Architecture (SOA) in most cases. A lot of people feel strongly that SharePoint isn’t the single source of truth for data, that may be the case, but SharePoint is a tool that does aggregate data and adds value to it (a user might create a list with BDC data with additional columns describing some business function), this framework is designed to make this data more accessible to an organisation trying to construct some form of SOA.

The URL Format

A REST API that sits over the object model would provide the best of both options, we could craft a simple URL that returned the items that we are after such as:

http://mashserver/Site/            -- returns all sites
http://mashserver/Site/all/            -- same as above
http://mashserver/Site/get/{guid-id}    -- returns the selected site

http://mashserver/List/                  --returns all lists that the user has permissions for
http://mashserver/List/forsite/{site-guid-id}   -- returns all the lists for the given site id

http://mashserver/ListItems/get/{list-guid-id}  -- returns all the items in the list,

http://mashserver/BDC/   --Return all the BDC applications

http://mashserver/Permission/site/{site-guid}   --Return objects representing the security ACL’s on the given object

The REST API should expand across all areas of the SharePoint system. Each action should be decorated with an accepted verb type attribute which MVC provides.

The Return Values

We could build a HybridResult that looks at the HTTP headers to determine the accepted input and then either return JSON or XML:

In fact Omar has already provided a nice starting platform.

This HybridResult can also be smart enough to return a 404 if the object we are trying to serialize is null. If we get any security exceptions we can set the return status code to 403, again the MVC provides a nice mechanism to support this via it’s Error Handling attribute.

Problems

• Do we build our own object model, reinvent the wheel?

I think the answer is yes, we can’t serialize the SharePoint object model to our needs as a REST API, in some cases we want to return properties in a form that would be easy to use from JavaScript. We often don’t want to return the whole object graph, if you ask for all the lists, you really don’t want to have a list object returned will a collection of list items. By using the new language features in .NET 3.5 we can build extension methods that provide a neat way to convert the existing Object Model entities to those created by the MVC framework.

• Security – The double hop issue

Since the API is going to make heavy use of the object model, it’s going to have the same limitations as the object model, i.e. the API web sites will need to live on the same server as SharePoint unless the double hop authentication issue is taken care of via the use of Kerberos, which is a likely event in most larger organisation.

 Features - Thoughts?

So what do you think? Is a REST API for SharePoint something that would be useful? I’ve already started developing some proof of concept prototypes which I’ve included on the project’s Codeplex site:  http://www.codeplex.com/REST4SharePoint so please leave any feedback there.

What features do you think it should include?

What are your thoughts?

What obvious thing have I missed?

JQuery is my all time favorite JavaScript library, it's so simple to use and incredibly powerful, but if you include all the plugins that are available, I just don't think that you would find a better tool for client side scripting.

My favorite validation plugin is the 'Validation Plugin', let me give you an example of how it is used:

Lets say you have a signup form, you want the user to select a user name, a password with confirmation and an email address, assume all of this is inside a form tag named 'signup'.

All of the HTML input element ids are 'Password', 'ConfirmPassword', 'Email'.

The JavaScript would be:

<script type="text/javascript">
$().ready(function() {
$("#signup").validate({
        rules: {            
            UserName: {
                required: true,
                minLength: 2,
                remote: "/Account/CheckUserName"
            },
            Password: {
                required: true,
                minLength: 2
            },
            ConfirmPassword: {
                required: true,
                minLength: 5,
                equalTo: "#Password"
            },
            Email:{
                required: true,
                email: true,
                remote: "/Account/CheckEmail"
            }
        },
        messages: {
            
            UserName: {
                required: "Please enter a username",
                minLength: "Your username must consist of at least 2 characters",
                remote: jQuery.format("{0} is already in use")
            },
            Password: {
                required: "Please enter a password",
                minLength: "Your password must consist of at least 2 characters"
            },
            ConfirmPassword: {
                required: "Please provide a password",
                minLength: "Your password must be at least 2 characters long",
                equalTo: "Please enter the same password as above"
            },
            Email: {
                required: "Please enter your email address",
                minLength: "Please enter a valid email address",
                remote: jQuery.format("{0} is already in use")
            }
        }
    });
});
</script>

Now notice how I used the remote property with '/Account/CheckEmail' and '/Account/CheckUserName', these are URL's that will be called by the client side JavaScript, they will pass along the current value of the textbox, so you could write server side code to validate the input, an ASP.NET MVC Controller Method could look like:

public JsonResult CheckUserName(string username)
{
    return Json(CheckValidUsername(username));
}

Notice the use of a JsonResult, The ASP.NET MVC framework is great for this type of thing, combine both JQuery and the MVC framework and you have a powerful combination, Jeff Atwood has come to the same conclusion and used both of these tools to build stackoverflow.com. 

All of the above code is so clean and easy to read, can you ever remember saying that about JavaScript code?