A service is as good as it's word

Wikipedia has contract defined as:

"In law, a contract is a binding legal agreement that is enforceable in a court of law or by binding arbitration. That is to say, a contract is an exchange of promises with a specific remedy for breach."

The exchange of promises principle is the same in software whereby a contract defines how clients can interact with a service. However unlike in law, if a service breaks it's contract the remedy for breach is typically an exception not a multi-million dollar law suit. A contract is a bit like a normal interface in code except with a web service, we can't compile directly against it. This is good news as this loose coupling of technologies means clients of a service can be created using any language and the service doesn't care as long as requests are made according to the contract. There are zero hard dependencies between client and service other than both have implicitly promised to adhere to the service contract.

The contract is written in a way that is independent of the service (or client) implementation. As long as there is enough information in the contract to enable both sides to communicate effectively then the medium doesn't really matter. In SOAP, service contracts are typically defined using WSDL but for our REST contract example we will use nothing more intimidating than a standard text document. In it we need to define one method (at the moment) for saving our blog details. The contract needs to define all inputs and outputs of this method including possible failure scenarios.

Our Blogging Service will conform to REST principles whereby we have the concept of resources being at the end of a url. It would seem wise then to start of by defining what resources our Blogging Service supports and where they are located. A resource hierarchy like the one below should suffice:

Blogging Resource Hierarchy

Sweet. So this tells us that at the end of the url http://services.digiati.com/samples/blogging/1.0 we can expect to find some service functionality for handling blog resources. It also tells us that the communication protocol in this case is http. Ok, that's fine, but we need a bit more if we're actually going to do something userful. Remember our user story - Save Blog Details? Ok, then let's define what the blog details are and how we send them to the service.

Method: Create Blog

The following information defines the CreateBlog method on the blogging service.

Excellent. So, now we know the following key points:

1. Where on the internet our service lives. The Url
2. The protocol and verb to use. Http POST
3. The message body format. xml
4. Expected response codes. Hopefully a 201 Created!

The contract also tells us what to expect when things don't go as planned.

An Http repsonse code of 409 indicates that the server received the request Ok but that for some reason it didn't like it. This basically equates to a business rule failure and we might find that the http response description gives us more information as to the reason for the failure.

An Http response code of 500 says that there was an internal server error. This is the one which puts egg all over a developers face if bugs are present but can also be a valid response if for whatever reason the service failed. Maybe a SSL certificate expired or a database connection has gone down. As much as is practically possible we should build our max-strength service in such a way that these kinds of errors are kept to an absolute minimum.

Finally we should note that these response codes are being returned by the service and not the server itself. The http response codes above will have explicit service code written to generate them. e.g. It is entirely possible that a 401 unauthorized response be received by the client if incorrect credentials are passed or anonymous access is not enabled on the server.

So that is a simple example of a service contract document which defines a method on our Blogging Service. In the next post we'll start to get down to the heady business of actually building the Blogging Service. If this is all new to you then you should familiarise yourself with the Microsoft REST Starter Kit and Spring.Net as this will be our starting point.

(See Twitter API or Amazon S3 for more examples of REST service contracts)