Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Tutorial: Using REST and OSGi Standards for Micro Services
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
- 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.
- 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/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 service that uses JAX-RS annotations: