Development of REST services in devops style

8 may 2019

Introduction
Document API
Add metrics (Observation layer)
Add resistance to errors (scalability layer)
Conclusion
Links

1 Introduction

Should we develop a service in a devops context, we will have to take into account both the logic of the business that offers the service (dev) and the operation of the service (ops). In this second task, scalability and observation take place, among other elements.

For dev, we can use for instance Spring Boot or Eclipse MicroProfile in Java language. The latter offers a subgroup of API Java EE focused on the development of services of API REST.

For ops, we have to add additional services focused on the control plane. For this we have different approaches:

Provide them from outside the code such as Istio or Kubernetes.
Provide them within the code if we have an available API that allows us to specify assertively the performance expected.

MicroProfile is an example of this second approach and offers a group of APIs that allow:

Developing the service
Making service scalability easier
Making the observation of the services easier

Figure 1: Layers of API MicroProfile

The lower layer is a subgroup of the APIs of JAVA EE. The second layer of API focuses on scalability and the higher layer allows observing the state of the services and gathering information that might be useful to improve them and correct mistakes.

Now, we are going to explain briefly three of the APIs that it offers.

2 To document the API

When a service-based architecture is developing, it is necessary to document the APIs. This can be conducted from the code itself by the use of annotations.

From these annotations a new endpoint is created in the URL http://HOST:PORT/openapi/ui that contains the API documentation. This allows us to get an overview of the API that offers the service, or the details of the operations from where we can send requests as the two following figures show:

Figure 2: Overview of the API that offers the service

Figure 3: Detailed description of an operation from where we can make requests.

3 To add metrics (observability layer)

It is important to be able to obtain metrics that allow observing the state of the service and the virtual machine. For this, the API MicroProfile Metrics can be used. Using this API, the service will provide an API REST for the query of the metrics.

This API provides us annotations such as: @Counted that allows to count the number of times a specific method is called; @Timed that allows to measure the time it takes to execute a method; or @Gauge that allows to show any value.

The metrics are available at URLs http://HOST:PORT/metrics or http://HOST:PORT/metrics/application to view only the metrics offered by the application.

Figure 4: Example of metrics before making requests.

Figure 5: Example of metrics after making different requests.

We could configure a service like Prometheus so it can check regularly this information and get graphs of those metrics that interest us.

Figure 6: Prometheus: example of the graph of a metric provided by the application.

4 To add fault tolerance (scalability layer)

There are different patterns that help make an application stronger:

fail fast that serves to notify as soon as possible the customer who calls of that the execution takes longer than the acceptable,
retry that serves to perform a number of retries when an error occurs before delivering a mistake to the client,
circuit breaker that serves to not making calls to services that are failing, or
bulkhead to limit the number of requests that a service can concurrently attend.

The API MicroProfile Fault Tolerance offers a set of annotations that allow you to configure how the service should behave against failures.

You can configure a maximum time using the annotation @Timeout so that if the execution of the method does not end at the specified time, the method execution will be stopped, ending with an exception of the TimeoutException.

The @Retry annotation is used to specify a number of retries. If the number of attempts is exceed then the execution will end with one exception.

5 Conclusions

In a devops context, it is necessary to focus on development, on how to get the functionality that the service must offer, and also its behaviour during execution, on how it must be behave in the event of its own failure or that of other services with which it interacts. We have shown that the API offered by Eclipse MicroProfile incorporates some of these elements of the control plane and offer us a series of annotations to inform the container that executes the service about what to do in case of failure. In two workshops of the subject Cloud Computing, the service has been developed, encapsulated in an image and a service has been generated with docker- compose that also integrates the Prometheus container.