RESTful microservices

In microservices architecture, each application is designed as an independent service. Any service can be a client that requests resources from another service, while also responding to requests from other services. REST has become 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. Therefore, the code of each service can evolve at its own pace, without affecting other services. This makes REST 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.

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.

What makes an API RESTful?

RESTful APIs use standard HTTP verbs for CRUD operations, and must pay special attention to whether the operation can be retried multiple times without changing the result (the concept of idempotence) and whether the results are safe to cache for future use (the concept of being safe).

  • POST operations are used to create or update resources, but they can’t be invoked repeatedly. If a POST resource is invoked multiple times, it creates a new, unique resource with each invocation.

  • GET operations can be invoked repeatedly, without causing side effects. They should only be used 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 invoked multiple times.

  • DELETE operations can be invoked multiple times. Even though a resource can only be deleted once, and the response code will be different on subsequent invocations (e.g. 404), 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 appropriately, so that operations can be idempotent and safe, wherever possible.

Generating and 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.

There are two ways to create an API:

  • Start with an OpenAPI definition: This approach begins by creating an OpenAPI definition in a language independent format (usually YAML). Then a code generator creates a skeleton implementation, and builds the service implementation from there. This pattern, favored by companies that have a central API design team, enables development and test to progress in parallel. The OpenAPI definition is a contract, an agreement between different teams for how the API will be designed.

  • Start with code: The service implementation code is the source of the API definition. This approach is beneficial for applications with an experimental aspect to them, since the API definition evolves as the services becomes more developed and defined. It is also is well-suited to Java, which has excellent support for generating OpenAPI documents from annotation-based REST frameworks.

In either case, working with an OpenAPI definition helps identify where the API is inconsistent, or difficult to understand from a consumer point of view. The OpenAPI definition can also be used to generate client stubs in various languages, which can then call the service or write integration tests.