Tutorial: Using REST and OSGi Standards for Micro Services

Introduction

It's currently popular to create REST-based networked services. This is understandable, as the ubiquity http/https, the simplicity of the REST approach, and the availability of open, cross-language object serialization formats like JSON and XML, along with the availability of quality distribution frameworks all make it easier than ever to define, implement, and deploy a service and it's associated API.

One thing that is relatively new, however, is that there are now open standards that deal with two levels of concerns

1. Transport/Distribution-Level Concerns: What protocol and serialization format are to be used? How to support cross-language type systems? How to be as bandwidth efficient and performant as possible? How to handle network failure? etc.
2. Service-Level Concerns: How to discover the service? How to version the service? How to keep the service and clients/consumers separate from the underlying mechanisms/implementations?, How to secure the service? How to describe and document the service so that others may easily understand and use it? How to combine services, etc.

Transport and Distribution Concerns

From the service implementer's perspective, the selection of a framework or implementation makes de-facto design choices about transport or distribution concerns. For example, some REST frameworks use XML, some JSON, some support both. However, once such a framework is chosen the service implemented and deployed, it can become very difficult, time-consuming, or even technically impossible to change to use other frameworks or distribution systems.

For REST-based services, however, standards are beginning to emerge that allow REST services to be defined and implemented without making a specific choice of distribution system or framework. One example in Java is JAX Remote Services or JAX-RS. JAX-RS defines/standardizes Java annotations for classes and methods that are to be exposed for remote access. JAX-RS implementations then use these annotations to 'export' the service (make it available for remote access) and handle the mapping between http/https requests, and the appropriate method invocation. For example, here's a small 'hello-world' service that uses JAX-RS annotations:

import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
 
// The Java class will be hosted at the URI path "/helloworld"
@Path("/helloworld")
public class HelloWorldResource {
 
    // The Java method will process HTTP GET requests
    @GET
    // The Java method will produce content identified by the MIME Media
    // type "text/plain"
    @Produces("text/plain")
    public String getClichedMessage() {
        // Return some cliched textual content
        return "Hello World";
    }
}

One very useful aspect of the JAX-RS annotations is that multiple implementations may exist, and it is relatively easy to switch from one implementation to another.

Service-Level Concerns

Although frequently of secondary concern to service implementers, service-level concerns are typically of primary importance to service consumers. For example, before I can use any REST-based service, I have to know about (discover) the service and needed meta-data: the service location (i.e. it's URL), what methods exist and arguments are required, and what can be expected in response. Additionally, what version of the service is being accessed, what credentials/security are required, what are the run-time qualities of the remote service?

OSGi Remote Services

In recent releases the OSGi Alliance has defined a specification called Remote Services (chapter 100 in the enterprise spec). Along with the Remote Service Admin specification (chapter 122 in enterprise spec), Remote Services defines ways to express answers to service-level concerns in an implementation-independent way, similar to what JAX-RS does for transport-level concerns. For example, the Remote Service spec allows meta-data for service type, service version, service endpoint/URL identification, security, and quality of service properties to be communicated between service implementer and service consumer without referring to any Remote Services implementation. Further, Remote Services/RSA defines a way to dynamically discover and un-discover remote services, allowing for easy consumer support for networked and frequently unreliable services.

Several implementations of OSGi Remote Services exist, including open source ECF, CXF, Amdatu and commercial implementations.

OSGi RSA has the concept of a distribution system responsible for exporting a local service and making it available for remote access. According to the specification, many distributions systems may be used even for a single service. ECF's implementation is unique because it has an open API for creating/adding new distribution providers. Currently, ECF committers have implemented the following distribution providers

• ECF 'generic'
• r-OSGi
• Java Messaging Service (JMS)
• MQTT
• Hazelcast
• JavaGroups
• Jax-RS/Jersey

Jax-RS and OSGi Remote Services Together

Since ECF's RSA implementation implements the OSGi RS and RSA specifications, and Jersey implements the Jax-RS specification, it's possible create and export a remote service that deals with both the transport and service-level concerns in a way completely standardized, and not dependent upon either the OSGi RS/RSA implementation (e.g. ECF), nor on the distribution system provider implementation (Jersey).

For example, here is some example OSGi code for exporting a remote service:

BundleContext bundleContext;
Dictionary<String, String> props = new Hashtable<String,String>();
// osgi property to signal to distribution system 
// that this is a remote service
props.put("service.exported.interfaces",*);
// optionally specify the distribution provider
props.put("service.exported.configs","ecf.generic.server");
// register (and export) HelloImpl as remote service described by Hello interface
bundleContext.registerService(Hello.class, new HelloImpl(), props);