REST standardization in the world of microservices

REST Standardization

REST standardization in the world of microservices


First of all, for those who do not know the REST concept, we could define it  as a style of software architecture for a client-server communication, through HTTP requests.

HTTP defines a small set of operations where the most important are: GET, POST, PUT and DELETE. All of them can be invoked through REST services and perform an action on the server (typically: consultations, insertions, updates or erasures).

Nowadays it is very popular due to the rise of microservices, the simplicity and readability in the programming code are the main advantages. On the other hand, there are a number of negative points that we could mention:

  • Generated Documentation: If another team wants to consume services, it will need a documentation of all the REST services generated along with the parameters needed to invoke them (something quite tedious). On the other hand, we can also add to the people in charge of the project, normally non-technical staff.
  • Little Standardization in the Implementation: When a developer begins to implement the solution, it is found often that the programming language provides different mechanisms, or even frameworks of third parties, to do it. This means that a common methodology of development does not exist, undermining the future support.


A new way to specify the REST communication for all audiences

In this way, the need arises to define metalanguages that are simple to understand by anyone, benefitting non-technical responsible people and those teams that is going to consume the developed services.

Nowadays there are several metalanguages/specifications, although we will remain with “Swagger” and “RAML” for this posr. We do not want to get in depth in any of them, because each one has its peculiarities, but we are interested that you discover the common concepts and power that offer to us.

Basically, in both cases everything is defined via a YAML file showing information of the REST endpoints, sending parameters, response parameters, etc. As you know, the use of YAML is also in fashion because it is easy to read by a human being, as opposed to XML or even JSON.

Below, we show an example of how a YAML file would like:

swagger: '2.0'
host: localhost:8080
basePath: /
  version: 0.0.0
  title: Simple-API
  description: my project description
      operationId: myOperationName
        - 200:
          description: OK

As we can see through the Swagger specification:

  • All our endpoint will be under the host “localhost:8080”
  • It will accept “http” requests (scheme)
  • The defined endpoint is GET that it will be invoked under a petition “/”, that is to say: http://localhost:8080/
  • The responses to these requests will be type “200”

Simple, doesn’t it? 😉

Standardizing the implementation of REST services

As it was mentioned in the first paragraph, one of the problems that the use of REST services has is the difficulty to find a common method to all developers.

There are different Internet projects whose main idea is to process a YAML specification as shown in the previous point, to generate source code and documentation, and in this way, the developer forgets of how to implement the client-server interaction, worrying only about its business logic.

Below, we advise you to visit any of the links below so you can see the different alternatives:

  • BBVA’s code generator (
    • Nowadays it has a lot of life as a proyect in Github.
    • It consumes Swagger although it is thought in the future to parse also RAML.
    • It generates code server Spring MVC and JAXRS, and client code JAXRS and Javascript.
    • Once generated, it is practically “plug & play” offering in addition random “mocks”.
  • Swagger’s code generator (
    • It offers different types of programming languages as a solution to the specification.
    • The generated code, unlike the previous one, it only offers the headers, forcing the developer to implement it.
    • This domain also offers tools for a very visual documentation.