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 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.
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
- http://my.library.org/books  which would be a collection of all books
- http://my.library.org/books/abc001 which references a particular book using its identifier abc001
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:
- 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.
- 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
JAX-RS has annotations to allow access to parameters of various kinds.
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.
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:
- To determine the request MIME type
- 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.