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.

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.

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.

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. For more information, see the Documenting RESTful APIs guide.

You can create an API one of two ways:

  • Design first
    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 is designed.

  • Code first
    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 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.

See also: