RESTful Automation and Governance

Introduction

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.

Service Dimensions

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.

Figure 1

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.

Figure 2

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 above-mentioned challenge.

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 RESTful services[REF-2].

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 response.

The following representation defines how the media type indicates the expected response by a certain invocation method:

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
Host: www.acne.com
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

1. 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.
2. 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
3. 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.
4. 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.

Figure 3

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.

For Example:

http://www.acne.com/account/en/1.1

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.

For Example:

GET /account
Host: www.acne.com
Accept: application/xml;lang=en;version=1.1

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 governance policy.

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.

Conclusion

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.

References

The Prentice Hall Service-Oriented Computing Series From Thomas Erl

Contact Information

info@servicetechmag.com
Tel: 1-800-579-6582
Fax: 1-604-904-4465