We are witnessing phenomenal growth in the adoption of open and proprietary REST-based services. Enterprises are increasingly turning to them for lightweight
HTTP-based distributed services and to model Service-Oriented Architectures. Such a proliferation mandates the use of policy-based governance, so that the developed
artifacts coexist harmoniously with supporting automation tools. It is through such coexistence that enterprises and organizations can take advantage of enhanced productivity
and quality gains. This article describes an approach of utilizing HTTP content negotiation in the context of JAX-RS-based RESTful service and the WADL service description to
govern the versioning, language encoding, and payload dimensions of services.
Given the possible number of combinations for client scenarios, the service must adapt its response in order to be usable. For instance, the client and server may
have completely in-dependent lifecycles since they are typically developed and managed by independent teams. Therefore, the server may have to support multiple versions
simultaneously. Similarly, different clients or consumers may have varying locale and encoding requirements – all of which the server needs to support simultaneously.
When using the systems data model in integration we can see that for simple integrations involving only two systems, it may be easier, but for more complex problems
involving more than two systems, the mapping grows exponentially and using the corporate data model becomes easier and faster. The problem is the complexity of interfaces always tends
to increase, and simple interfaces become complex.
RESTful Service Lifecycle
IT systems must march in step with ever-changing business objectives. However, in a large and complex enterprise, expecting all the segments of IT infrastructure
and assets to move at the same pace and react simultaneously is often an unreasonable expectation. Therefore, versioning of services and formulating an appropriate deployment
schedule is a critical enterprise governance activity.
The diagram above indicates that a service will have to transition through active, deprecated and sunset stages. This would enable the clients time for transitioning
to the next version of the service. Typically, organizations have a fixed time span between service version commission and sunset.
In the following sections, we will examine some of the tools to build RESTful services, and also the techniques of managing some of the complexity arising from the
Jersey and JAX–RS
JAX-RS is a framework that relies on Java annotations to provide a bridge between HTTP request/response and Java artifacts[REF-1].
- It binds specific URI patterns and HTTP 1.1 operations (GET, POST, PUT, DELETE) to specific methods in user-defined Java classes. It utilizes HTTP content negotiation for this purpose.
- It Decouples data format marshalling and unmarshalling from Java data objects using mes-sage body readers and writers.
- It Maps application thrown exceptions to HTTP response codes and messages.
Jersey is an open source implementation of JAX-RS. Among its many noteworthy features is the ability to automatically generate WADL files as a service descriptor of
WADL the Client Server Arbiter
The Web Application Description Language (WADL) defines the REST service as set of meth-ods on resources. The request and response elements within the methods are
defined in terms of representations. These representations are defined in terms of media types that are based on a specific set of service dimensions in order to retrieve the desired
The following representation defines how the media type indicates the expected response by a certain invocation method:
||<representation id=″repXMLProperties″ mediaType=″application/vnd.acme+xml;version=1.0″ element=″yn:Properties″
<doc xml:lang=″en″ title=″All Properties after a query″/>
WADL files can embed service related documentation and be used to automatically generate client side stub code.
HTTP Content Negotiation
One of the most powerful capabilities of HTTP is to allow clients to specify to the server how they would like its responses formatted given a certain set of
parameters (version, locale, en-coding or payload). The protocol that enables this is called HTTP content negotiation, or "con-neg," for short. This protocol is the cornerstone
in the precise definition of a RESTful service response for a given request.
GET /page/restful/accounts HTTP/1.1
Accept: application/xml, application/xhtml+xml, text/plain, image/png
The HTTP request above defines the different payload types that can be accepted by the client.
Typical RESTful Service Delivery
- The lifecycle of RESTful service provisioning begins with creation of services using the JAX-RS API. The names of the methods must follow a certain standard
convention that would illustrate the dimensions it represents for example in terms of version, locale and encoding.
- JAX-RS allows for easy query of WADL associated with the created service. Authoring of the WADL is not necessary and it is automatically generated by HTTP
query as follows. If http://www.acme.com/account is the base URL of the service
- GET http://www.acme.com/account/application.wadl returns the required filWADL2Java. It is an open source program used to accept WADL and create a corresponding
stub program for clients. It utilizes the JAXB implementation to abstract out the construction of the HTTP URL comprising the request header and query parameters. It also
encapsulates the HTTP request dispatching process such that the client needs not to be concerned about these intricacies. Further, the stub code uses JAXB to marshal the HTTP
response to the Java client-side defined objects.
- The client invokes the methods pertaining to a certain set of dimensions of interest in the stub to make HTTP requests. The stub will be responsible for making
the HTTP request as per the content negotiation rules defined in the WADL file for that resource.
The Governance Challenges
A modern software system is like an invariably complex ecosystem of interdependent com-ponents working in tandem. Even if each of these components function flawlessly
on their own, one of the prominent goals of a governance model is to ensure they also function flawlessly in concert.
In the previous section, we have seen an elaborate system of interdependent tools to auto-matically create artifacts. These tools greatly enhance the productivity of
development teams and, hence, reduce costs.
However, certain advanced features of products, such as JAX-RS, do not lend themselves to the wellbeing of the above-mentioned ecosystem. For example, in a bottom-up
development model wherein the services are created before WADL description files, instead of defining the dimensions of the method declaratively as annotations, they can be
programmatically defined as a set of Variants inside the Java code. The automatically generated WADL (step 2) in this case will not have any knowledge of these variants and will
apply a generic */* content negotiation representation to this method. This in turn will result in erroneous downstream code generation.
Policies must therefore be put in place to ensure that the capability of creating new media types within the content negotiation framework is gainfully leveraged.
These media types must be declared with @Produces annotation for each method and not defined programmatically in Java code.
Dimensions such as version can also be defined as a part of HTTP URL request. This type of request representation is supported by a WADL description.
However, such a URL cannot be bookmarked in the browser since the supported version is time-sensitive. Therefore, it is recommended to take advantage of the Accept
HTTP header request attribute. Normally this header value is transparent to the client since the stub adds it to the request header.
The URL in the case above effectively becomes agnostic of requested service dimensions and can be easily bookmarked. The client side stub is vital to the generation
of such a scheme for generating bookmarkable URLs.
Therefore, the mechanics of where service dimensions such as versions are defined on the client must be judiciously chosen and are a vital part of enterprise
Application of these policies is further complicated by the fact that they need to constantly adapt to a moving target of supported versions, locales, encodings,
payload etc. In keeping with the scheme in Figure 2, policies can be written such that for any given time frame, we can ensure that the service dimensions defined in the WADL
file media type adhere to the project plan. Beyond a certain threshold of complexity, utilization of automated governance tools becomes essential.
Typically, these policy-based governance tools allow for ease of configuration of policies in addition to management reporting of the conformance of developed
artifacts to these policies. They also are able to interface with multiple development assets in the organization, such as source control management tools, registries and integrated
development environments (IDE′s) to provide centralized and uniform policy enforcement across the entire software development life cycle.
RESTful services are about exploiting HTTP to create resources adhering to the SOA paradigm. This article explains the ecosystem of artifacts and tools that make it
easy to build RESTful services. However, responding to the moving target of supported version, locale, encodings and payload in an enterprise ecosystem can introduce significant
long-term operational complexity. WADL descriptor files can alleviate this complexity to some extent by declaratively associating these variable dimensions to resources and automating
the creation of client-side stubs. However, in a scenario of a large number of dynamic services provided and consumed by a multitude of organizations, reliable policy-based governance
tools become indispensable.
[REF-1] RESTFul java with JAX–RS — O′Reilly publication by Bill Burke
[REF-2] Jersey Library http://jersey.java.net/