Motivation

Open API is the most popular approach to design, build and document REST APIs. It does not depend on a particular language. The contract provided by the swagger (Open API implementation) guarantees that the REST server is compatible with the specification. The specification is the single source of truth for consumers (web interface, CLI, third party integrations).

Description

Code-first approach

Code-first approach is suggested. One writes backend code and after that, the specification is generated from this code.

Typical development lifecycle for new endpoint:

1. Implement backend and test endpoint and annotate the method with swagger annotations
2. Build backend module and check that Open API spec is generated
3. Build client module 
4. Use generated client

Additional dependencies

REST module will have additional dependencies:

• io.micronaut:micronaut-inject:jar:3.4.1
• javax.annotation:javax.annotation-api:jar:1.3.2 (transitive from micronaut-inject)
• jakarta.inject:jakarta.inject-api:jar:2.0.1
• io.micronaut:micronaut-core:jar:3.4.1
• io.micronaut:micronaut-http-server-netty:jar:3.4.1
• io.micronaut:micronaut-http-server:jar:3.4.1
• io.micronaut:micronaut-router:jar:3.4.1
• io.micronaut:micronaut-http-netty:jar:3.4.1
• io.micronaut:micronaut-buffer-netty:jar:3.4.1
• io.micronaut:micronaut-runtime:jar:3.4.1
• io.micronaut:micronaut-http:jar:3.4.1
• io.micronaut:micronaut-aop:jar:3.4.1
• io.micronaut:micronaut-context:jar:3.4.1
• io.micronaut:micronaut-core-reactive:jar:3.4.1
• Io.micronaut:micronaut-json-core:jar:3.3.3
• io.micronaut:micronaut-jackson-core:jar:3.3.3
• io.micronaut.serde:micronaut-serde-api:jar:1.0.1
• io.micronaut.serde:micronaut-serde-support:jar:1.0.1
• javax.validation:validation-api:jar:2.0.1.Final (transitive from micronaut-runtime)
• jakarta.annotation:jakarta.annotation-api:jar:2.0.0
• io.swagger.core.v3:swagger-annotations:jar:2.1.12

Modular architecture support

TBD

Implementation draft

Here is an example of GET /management/v1/configuration/node endpoint: 

@Controller("/management/v1/configuration/node")
@Tag(name = "nodeConfiguration")
public class NodeConfigurationController {

   //…

   @Operation(operationId = "getNodeConfiguration")
   @ApiResponse(responseCode = "200",
           content = @Content(mediaType = MediaType.TEXT_PLAIN,
                   schema = @Schema(type = "string")),
           description = "Whole node configuration")
   @Produces(MediaType.TEXT_PLAIN)
   @Get
   public String getConfiguration() {
       return …;
   }

Run this command to generate the specification:

mvn -pl modules/rest -am clean package -DskipTests=true 

The specification generated:

/management/v1/configuration/node:
 get:
   tags:
   - nodeConfiguration
   summary: Returns node configuration in HOCON format.
   description: Returns node configuration in HOCON format.
   operationId: getNodeConfiguration
   parameters: []
   responses:
     "200":
       description: Whole node configuration
       content:
         text/plain:
           schema:
             type: string

To build the java client run:

mvn -pl modules/rest-client -am clean package -DskipTests=true

The client usage example:

ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("http://localhost:" + BASE_REST_PORT);
var nodeConfigurationApi = new NodeConfigurationApi(client);

String configuration = nodeConfigurationApi.getNodeConfiguration();

API

Configuration REST API

This REST group provides methods to read and update node/cluster configuration.

Management REST API

Manage cluster state.

Topology REST API

Provide information about cluster topology.

Version REST API

Provide the build version for the node. 

Open tickets

TBD

Closed tickets

TDB