A Specification for defining REST Services

by Guilherme Gomes 1.Introduction

Service oriented applications have become increasingly appealing to developers due to several reasons. One of them is Service-Oriented Front-End Architecture (SOFEA), an alternative solution to the typical MVC architectural pattern. The design of web applications is in general based on MVC, and in many cases, all of the MVC layers are implemented in the same application. One relevant issue of this approach regards the design of a User Interface (UI), which is not trivial, due to the constraints related to UIs for the web, the great number of different Web UI technologies and associated development methods. The concept of SOFEA allows removing from the server the responsibility of application presentation. The interface is handled by another application which remotely uses the services. It allows developing applications for specific presentation technologies, while maintaining the investment on the core server. Another reason is Service Oriented Architecture (SOA) which can be defined as an architecture style to create applications based on loosely coupled services from distinct providers for specific purposes. The developers define what the application needs, which services will be used, which providers will be chosen, and assemble an application based on this information. Finally, there is also Cloud computing which relies on the deployment of applications on a computing grid instead of a specific machine or piece of hardware, allowing the dynamic allocation of resources from a pool of shared computational assets. Cloud Computing is relevant since it transforms world-class, high-priced availability, scalability and redundancy systems, previously only available to a select few companies, and turns them into a publicly available low-priced commodity. These developments create a scenario where a more straight-forward, lower-entry barrier service solution becomes relevant. REST was first introduced by Roy T. Fieldings doctoral thesis and since then has gained much attention as an architectural style. Due to its recent popularity, many web development frameworks support or are in the process of adding support for REST services. One particular effort has been done towards providing Java-based REST support via annotations on Plain Old Java Objects, as described on JSR 311 and its default Jersey implementation. Another effort is the Web Application Description Language (WADL) which was created with the goal of providing a machine processable description of HTTP-based Web applications. Generating code to support REST services from WADL files is possible for specific platforms such as java. Despite these efforts, some issues remain in developing REST applications. Even though there is a growing set of libraries and tools for several programming languages to facilitate the development of REST services, there is no common agreed industry-wide standard to describe an applications service layer. REST principles are platform independent, but current REST tools are very much platform specific. Developers are required to learn a new set of tools for each platform they choose to implement the services. Another issue is that any application development requires a lot of testing which lead to small changes. Developing a service layer is not different, but the existing tools dont provide a dynamic update mechanism. In many platforms, these changes require the application to be restarted in order to be applied. In the case of the Java platform, small code changes can be Hot-Swapped, but any minor change to the service layer requires a restart. Even tough this is a very common use case, no description of a platform-independent interface exists in order to dynamically apply changes to services.

2.SPECIFICATION
Designing a RESTful application requires the organization of services, which implies choosing the resources to be exposed, how they are identified by URIs, which relations exist among resources and which HTTP methods and representations are supported. It is important at this point to distinguish the REST specification from a REST Server. A REST Server in the context of this work is defined as an application that provides an implementation of the specification, as described in the following sections.

2.1 Resources and URIs

Since URIs are an integral part of REST services, it is relevant to define how they should be structured and used in the specification. URIs may be comprised of static sections and parameters. For instance, an author resource could use: /authors/{id} where /authors is the static part of the URI, followed by {id}. The last section is a parameter, where the http client
Copyright 2008 by Guilherme Gomes All rights reserved Page 1 of 6

A specification for defining REST services

specifies the value. As this is a relative URI, if the application was to be hosted at http://test.com, then the authors resource would have the following absolute URI: http://test.com/authors/{id} For instance: A GET request made to the absolute URI of http://test.com/authors/245 describes a directive to fetch data relative to the author identified with the id 245. Likewise, a documentation module could use URIs with the following structure: /documents/{doc-id}/chapter/{chapter-id} Where doc-id would be the identification of the document, and chapter-id would be the identification of a chapter within the specified document. For obvious reasons, two parameters with the same name are not supported. The code that processes the client request receives a list of parameters, mapping each parameter name to a value. For instance, the code handling this request would receive a parameter id=245. With this information, it would make the appropriate calls to the persistence layer to retrieve the authors data based on that id and return a representation of it.

2.2 Design and Organization of REST Services

As an URI identifies a single resource, a collection of closely related resources can be identified as a module. For instance, in a Costumer module the resources would be the costumers, their phone numbers and their home address. In a billing module, the resources would be invoices, receipts, acquired items and so forth. An application is composed of one or more modules. For example, a billing application would be made up of a costumer and billing module. The proposed high level organization of the specification can then be defined as depicted in Figure 1.

Figure 1: Class model for high level organization The functionality required for a REST application in the context of this work depends on several aspects of the HTTP specification, for instance, which HTTP methods can be applied on the resource and which representations of the resource are supported. Each resource, besides its URI, can define a set of HTTP methods, and each HTTP method can define a set of mimetypes to identify which representations are accepted (Figure 2).

Figure 2: Class model of low level structure As GET, PUT and POST actions deal directly with resource representations, they need to declare a list of supported representations, such as XML, JPEG and others, identified by a corresponding MIME type. Contrarily, DELETE simply removes the resource and has no need for supporting resource representations.

2.3 Code and Handling Requests

Concerning implementation, the code that actually provides a service must be identified and handle the HTTP request. As any client request will be performed on an URI which represents a resource, handling the request consists of fetching the code associated with that specific resource in the specification, passing it the necessary parameters and finally executing it. However, this approach is simplistic, since the most common use cases is to process the request based on the type of HTTP command and the required mime-type. Another aspect that should be considered is code reuse. Consider the common case where some code fetches data from the persistence layer and creates an XML representation of a resource. Indeed, this exact same code can be used for all GET requests for a text/xml mime type regardless of which resource receives the request, with only a few necessary changes in parameters. The solution proposed solves theses issues defining a three staged request process sequence, as illustrated in Figure 3.

Figure 3: Request processing sequence On each stage, developers can associate a handler, which is any code that performs some processing based on the request. This code can provide the response and terminate the sequence, or perform any required processing and let the sequence continue.

Copyright 2008 by Guilherme Gomes All rights reserved

Page 2 of 6

A specification for defining REST services

The default behavior of the sequence is to execute the resource handler, then move on to the handler of the corresponding http method, and finally determine the requested mime-type and process the associated handler. It is possible to set handlers on all or only on some stages of the process sequence. At any time, if there is no specified resource, http method or related mime-type that matches the request, an http client error is returned, as the request is not supported. For this approach to work, it is required that all handler code has access to a specific set of information crucial for its execution, such as the HTTP request and response details. It is also required some form of passing data between handlers at different stages in the request processing sequence. This specification does not enforce a specific programming language or platform for handlers, allowing the use of scripted, compiled languages, or even both. Therefore compatible REST servers can be implemented in any chosen platform or language.

2.4 REST Configuration

The configuration files are XML-based since it is a standard for providing interoperability across different platforms, it is both human and machine readable, and there are countless tools available for it. An application is comprised of several modules, and can be defined as:
<application name=CRM active=true> <relative-uri>app</relative-uri> <modules> <module name=clients /> <module name=billing /> </modules> </configuration>

As the module is a set of related resources, the configuration file is comprised of a list of resources:
<module name=clients active=true> <relative-uri>test</relative-uri> <resources> <resource></resource> <resource></resource> </resources> </module>

The active attribute determines if the application/module is actually deployed in the server. The relative-uri attribute in the application and module is used to build the URI for resources. In this example, all resources from the client module in the CRM application will have a prefix of /app/test in their URIs. The resource declarations are demonstrated by this example:
<resource active=true> <target-uri>/clients/{id}</target-uri> </resource>

The relative URI of a resource is indicated as well as the deployed attribute which determines if the resource is active. If the application was hosted at http://xpto.org, this resource would be at http://xpto.org/app/test/clients/{id}, where id is the parameter. Any calls made to http://xpto.org/app/test/clients/{id}, such as http://xpto.org/app/test/clients/15, would be directed to this resource. It is important to add a handler to the resource in order to deal with the requests made to this URI:
<resource active=true> <uri>/clients/{id}</uri> <handler active=false> <path>/path/resourceHandler.groovy</path> <parameters> <parameter name=X value=5 /> </parameters> </handler> </resource>

The handler specifies the path to the file with the code to be executed in case of requests to this resource. Parameters can be set as a list of name-value pairs to be used by the handler in run time. This approach promotes reusing the same handler in many resources by simply changing parameters. For this example, handlers can be identified as Java classes using their fully qualified class names. Handlers implemented as Groovy scripts and JTActions will define their file paths and extensions - .groovy and .xml, respectively. The processing sequence supports handlers for HTTP methods and mime-types, as demonstrated in the following example, where a handler is specified for the resource, as well as for the GET and DELETE actions. The resource handler is useful if, for example, there is common code that must be executed for both http methods.
<resource active=true> <target-uri>/clients/{id}</target-uri> <handler active=true> <path>/test/client/handler.groovy</path> </handler> <http-methods> Copyright 2008 by Guilherme Gomes All rights reserved Page 3 of 6

A specification for defining REST services

<http-method name=GET active=true> <handler active=true> <path>/script/getHandler.groovy</path> </handler> <mime-type-handlers> <mime-type-handler> <mime-type>text/xml<mime-type> <handler active=true> <path>/test/getXML.groovy</path> </handler> </mime-type-handler> <mime-type-handler> <mime-type>application/pdf</mime-type> <handler active=true> <path>/test/getPDF.groovy</path> </handler> </mime-type-handler> </mime-type-handlers> </http-method> <http-method name=DELETE active=true> <handler active=true> <path>/script/deleteHandler.groovy</path> </handler> </http-method> </http-methods> </resource>

The specification also supports extending the four basic HTTP methods, by the use of the name tag. Any GET requests are handled by the getHandler.groovy file, and if the client specified the desired media type as text/xml or application/pdf, then either the getXML.groovy or getPDF.groovy file will also be executed. This granular approach of associating handlers with specific mime media types further divides the problem, allowing code responsible for the creation of a specific representation to be isolated and developed independently. This specification allows an application to read a few XML files and set up the described REST services.

2.5 REST Administration

To allow an application to change its REST services on the fly instead of restarting the full application requires defining and implementing an administration service system. For this purpose, we defined a specification of a REST service. It is based on the configuration specification which makes the access and utilization of the administration service a straightforward task. Consider the case of a REST Server at http://xpto.com/. The REST administration service could use the base URI of http://xpto.com/admin/. Retrieving the list of the existing applications on the server would consist of a GET on http://xpto.com/admin/applications which would return:
<list> <application name=crm active=true uri=http://xpto.com/admin/applications/1> <application name=test active=false uri=http://xpto.com/admin/applications/2> </list>

In the following examples, in order to reduce URI length, all URIs will be related to http://xpto.com/admin. Additional information on the first application is available via a GET on the following URI:
http://xpto.com/admin/applications/1 <application name=crm active=true uri=/applications/1> <modules> <module name=clients active=true uri=/modules/1 /> <module name=billing active=true uri=/modules/2 /> </modules> </configuration>

This specification is identical to the regular REST configuration files except that all resources now have an URI attribute which represents a hyperlink which allows incremental data fetching instead of obtaining the entire configuration at once. If a GET was made for http://xpto.com/admin/modules/1 the following XML would be obtained:
<module name=xp active=true uri=/modules/1> <resources> <resource active=true uri=/resources/1/> <resource active=true uri=/resources/n/> </resources </module>

The information on the first resource would be:

<resource active=true uri=/resources/1> <target-uri>/test/clients</target-uri> <handler uri=/handlers/34 /> <http-methods> <http-method name=GET active=true uri=/http-methods/4/> Copyright 2008 by Guilherme Gomes All rights reserved Page 4 of 6

A specification for defining REST services

</http-methods> </resource>

Performing a GET on http://xpto.com/admin/handlers/34 would return:

<handler active=true uri=/handlers/34 > <path>/filepath/to/getClientList.groovy</path> <parameters> <parameter name=X value=245 uri=/parameters/56/> </parameters> </handler>

Further requests would provide information on the GET handler as well as more specific mime type related handlers. Adding new information is straightforward as well. In order to add a parameter to the handlers parameter list simply POST on http://xpto.com/admin/handlers/34/parameters with a content type of text/xml mime media type and a body of <parameter name=Y value=31/>. The response would contain the XML representation of the newly created parameter with an URI attribute of http://xpto.com/admin/parameters/{id} where id would be the index of the parameter. Performing changes to existing resources is also simple. For instance, deactivating a module consists of performing a PUT on http://xpto.com/admin/modules/{id}/active with a plain text content of false. Deleting a parameter consists of performing a DELETE to http://xpto.com/admin/parameters/32, for example. The parameter will also be removed from all handlers that referenced it in their parameter lists. Any changes to the configuration by the administration system will force an update. The server will change its deployed services on the fly, without any restarts. This allows faster and easier development and testing.

3.REST EDITOR
The REST Editor, as depicted in Figure 1, is a Java SWING application capable of creating and editing local configuration files, as well as using a remote REST administration service. Therefore, adding support for these specifications also means having access to a graphical tool to easily configure REST services. Any changes to the configuration performed on the editor are immediately dispatched to the administration service, enabling run-time changes on the server. Deactivating a resource or a full module can be done with a simple click on a checkbox.

Figure 1: Early version of the REST Editor This tool allows teams of developers to work in parallel in distinct modules or resources, each one performing changes to the application via the administration service. As the administration service is platform independent, the server can be implemented in any programming language. As long as the remote services to manage the configuration are available as specified, then the REST Editor can be used.

Copyright 2008 by Guilherme Gomes All rights reserved

Page 5 of 6

A specification for defining REST services

4. REST SERVER IMPLEMENTATION

The specifications presented in this project have been implemented in a reference REST Server. It is a standalone application in Java making extensive use of the RESTlet library and Groovy as scripting language. Handlers can be implemented as Java classes, Groovy scripts and JTAction XML files. The server proves the feasibility of the specifications presented by supporting the configuration files and administration services. It clearly demonstrates that it is possible to change the service layer on the fly without restarting the application, allowing code changes through the use of scripting languages. As a tool, it provides a lightweight environment to quickly prototype and develop REST applications.

5. TESTING
Any REST application can be tested with a browser for simple GET requests. For further testing, WizTools RESTClient 2.1 is recommended. RESTClient is capable of performing all standard HTTP methods, specifying header parameters, content and content type, as well as authentication configuration. This application can also save and load requests and responses, allowing developers to reproduce requests as the application is developed and test the services.

6.CONCLUSIONS
A specification for the definition and configuration of REST based web services has been presented, defining XMLbased configuration files as well as a remote administration service. This effort is further complemented by a GUI tool and a working implementation of the specifications. This work tries to solve some of the difficulties identified in developing REST based applications, namely, the lack of a platform-independent standard for the description and runtime administration of REST services and associated tools.

7.Links
Google Code : http://code.google.com/p/tabulasoftmed/ Downloads : http://code.google.com/p/tabulasoftmed/downloads/list Video Tutorials : http://tabula.softmed.org/?page_id=45 Blog : http://tabula.softmed.org/ Contact: [email protected]

Copyright 2008 by Guilherme Gomes All rights reserved

Page 6 of 6