REST Services: The Responsibilities of a Service Provider

December 2, 2009

RESTful services are particularly useful for Web 2.0 developers and are pleasingly easy to develop in Java using the Apache Wink implementation of JAX-RS. You can get more detail about REST starting here in Wikipedia in this posting I want to illustrate the significance of  JAX-RS by considering the responsibilities of the a developer who wants to provide a REST service. In a more detailed posting I describe in detail how to use Wink to create a few simple services for a Lending Library.

REpresentation State Transfer (REST) is concerned with the State of resources and passing of representations of that state between client and server. So, we need to understand:

  • what is meant by a resource
  • how URIs are used to specify particular resources
  • how requests to retrieve and manipulate the state of a resource are defined by the client
  • the representation of the state as it is transfered between client and server

Resources

Resources may be any entity (or collection of entities) owned by a service provider. They are often familiar business entities such as Customers and Orders. I am  library examples we might have Books and DVDs. We also treat collections of entities as resources, for example “All orders placed today” or “Books written by Alastair Reynolds”.

We can easily imagine a simple mapping between records in a Relational Database and the resources managed by a service provider. However we can also treat more abstract information as resources., for example “The temperature now in London” or “The current stock price for IBM on the NYSE”.

So our first task as a REST service provider is to identify the resources our service is managing. Typically we will give some detailed consideration as to how clients would like to refer to the resource and that leads to define the URIs by which clients with specify the resources.

URI

Strictly speaking REST services can use many different technologies, they are not limited to the use of Web technologies and HTTP protocols, but here I am going to focus on the most common case, accessing resources specified by a URI using HTTP (or HTTPS).

The service provider will define the URIs that specify particular resources. In our library example we might have

and we can similarly use URIs to specify more abstract information such as

We see here a more extensive URI hierarchy and this indicates the extent of design effort that may be required in the resource identification activity so that we can define the URIs to be used.

This leads to some specific implementation coding tasks:

  1. The URI http://my.library.org/books must in some way map to code that actually manages the book resources, and similarly the http://my.weather.org/current URI must be associated with the resource manager for the current weather resources.
  2. The resource manager must interpret more precise URIs in order to identify the specific resources. So  uk/london/temperature must be interpreted correctly, the implementer needs structured access to the URI.

The implementation tasks are addressed by JAX-RS, and in the more detailed article I describe how to use JSX-RS annotations to complete the service implementation.

These ideas are extended further to allow the passing of parameters in the URI, in the example the collection URI is  modified by some search criteria

http://my.library.org/books?author=doyle

JAX-RS has annotations to allow access to parameters of various kinds.

Methods

RESTful architecture using HTTP explicitly exploits of HTTP methods such as GET, PUT, POST and DELETE, to define actions on resources:

  • GET: retrieve a representation of the resources specified by the URI
  • PUT: replace the state of the resource specified by the URI with new values
  • POST: add a new resource, typically the URI will be that of a collection and the specified ID will be be generated by the resource manager or derived from the payload
  • DELETE: remove the resource specified by the URI

This too leads to specific coding tasks: the implementer needs to map from the HTTP method to the appropriate action.

Representation

The resource representation returned from  a GET or (for example) specified in a PUT can be in arbitrary format as specified by the MIME type of the request, usually that type would be application/xml for XML application/json for JSON.

From the service provider’s perspective this leads to two further tasks:

  1. To determine the request MIME type
  2. To parse requests or format responses in accordance with that type.

JAX-RS has annotation capabilities to deal with different MIME types, however the corresponding  parsing and formatting is not part of the JAX-RS as such, but rather is provided by JAXB, hence we will need to use some JAXB annotations when supporting the chosen MIME types.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: