RESTful microservices
In microservices architecture, each application is designed as an independent service. REST is a valuable architectural style for microservices, thanks to its simplicity, flexibility, and scalability.
One of the strongest advantages of REST for microservices is that services can communicate without requiring internal knowledge of one another. The code for each service can evolve at its own pace, without affecting other services. Therefore, REST is an especially good fit for microservices, which generally rely on small, autonomous teams to develop, deploy, and scale their respective services independently. Furthermore, in RESTful microservices, APIs are standardized according to the OpenAPI Specification, which provides a documented contract for how services are expected to communicate across ongoing development.
What makes an API RESTful?
RESTful APIs use standard HTTP verbs for create, retrieve, update, and delete operations, and must abide by the concepts of idempotence and safety. They must pay special attention to whether the operation can be retried multiple times without changing the result and whether the results are safe to cache for future use. REST APIs implement HTTP verbs according to specific protocols:
POST operations are used to create or update resources, but they can’t be called repeatedly. If a POST resource is called multiple times, it creates a new, unique resource with each invocation.
GET operations can be called repeatedly, without causing side effects. They must be used only to retrieve information.
PUT operations update resources. They usually include a complete copy of the resource to be updated so that the operation can be called multiple times.
DELETE operations can be called multiple times. Even though a resource can be deleted only once, and the response code is different on subsequent invocations, the server remains in the same state through multiple invocations.
Well-designed REST APIs adhere to the HTTP protocol around resources and URIs, HTTP verbs, and statelessness. For example, REST APIs use HTTP verbs so that operations can be idempotent and safe wherever possible.
JAX-RS: an API for RESTful services
Jakarta RESTful Web Services (JAX-RS) is a Jakarta EE API for developing web services that follow REST principles. It specifies a collection of interfaces and Java annotations that simplify development of REST applications. Some of the key JAX-RS features include:
A collection of annotations for declaring resource classes and the data types they support
A set of interfaces that allow application developers to gain access to the runtime context
An extensible framework for integrating custom content handlers
By applying annotations to plain old Java objects, JAX-RS specifies a framework to bind URI patterns and HTTP operations to methods in your application classes. This framework provides a standardized way to interact with application resources over the web. The annotations are supported by any Jakarta EE-compliant application server, such as Open Liberty.
Open Liberty provides Java libraries that implement JAX-RS, so your applications remain lightweight, portable, and scalable. Support for JAX-RS on Open Liberty is enabled by the Jakarta RESTful services feature and the Jakarta RESTful Services Client feature. For more information, see the Creating a RESTful web service guide.
REST clients
A REST client is an application that invokes a REST API by making requests for resources. For example, if a REST API provides weather information for US cities, an application that follows REST principles to request the current temperature in Chicago is a REST client. REST clients are a lightweight solution to query and display data that is exposed by REST APIs. MicroProfile REST client provides a template interface for designing REST clients. It automatically generates a client instance based on what is defined and annotated in the template interface. For more information, see REST clients and the Consuming RESTful services with template interfaces guide.
Documenting RESTful APIs in microservices
MicroProfile Open API provides a Java API for the OpenAPI v3 specification, the de facto specification for RESTful services. MicroProfile Open API can generate a skeleton implementation of a REST API or expose the documentation for an already-implemented REST API. For more information, see API documentation with OpenAPI and the Documenting RESTful APIs guide.
MicroProfile and REST
Eclipse MicroProfile is a modular set of technologies for building microservices with REST APIs. These technologies help document your REST API, provide fault tolerance, manage authentication and authorization, monitor the metrics and health of your microservice, and more. Since most microservices are based on REST APIs, MicroProfile is a valuable resource for building robust, scalable applications. You can take advantage the full collection MicroProfile features for Open Liberty by enabling the MircoProfile convenience feature in your server.xml file.
