...

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

The current implementation does not support auto-generation for the API specification. The main value of this improvement is to add the possibility to generate the API specification from code.

Description

Code-first approach

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

...

• 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.3io.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

any other module that wants to expose an enpoint:

• com.fasterxml.jackson.core:jackson-annotations:jar:2.13.1
• jakarta.annotation:jakarta.annotation-api:jar:2.0.0
• jakarta.inject:jakarta.inject-api:jar:2.0.0:compile
• io.swagger.core.v3:swagger-annotations:jar:2.1.12
• io.micronaut.serde:micronaut-serde-jackson:jar:1.0.1
• io.micronaut:micronaut-jackson-core:jar:3.3.3
• io.micronaut:micronaut-json-core:jar:3.3.3
• com.fasterxml.jackson.core:jackson-core:jar:2.13.1
• io.micronaut:micronaut-context:jar:3.3.3
• io.micronaut.serde:micronaut-serde-api:jar:1.0.1
• io.micronaut.serde:micronaut-serde-support:jar:1.0.1
• io.micronaut:micronaut-http:jar:3.4.1
• io.micronaut:micronaut-inject:jar:3.4.1
• io.micronaut:micronaut-http-server:jar:3.4.1
• io.micronaut:micronaut-runtime:jar:3.4.1

...

Example of API evolution:

1. Add /api/v1. API version 1, openapi.yaml#version: 1.0.
2. Add backward compatible change to /api/v1.  API version 1, openapi.yaml#version: 1.1
3. Add breaking change to /api/v1, so introduce /api/v2. API version 2, openapi-v2.yaml#version: 2.0, openapi.yaml#version: 1.1.

Modular architecture support

Ignite modules can provide endpoints that will be included into the netty server by RestComponent at the build time. For example, the configuration module exposes /management/v1/configuration/node by declaring NodeConfigurationController and NodeConfigurationRestFactory. Then ignite-configuration module is added as a dependency for the ignite-rest module. And NodeConfigurationController is added to @OpenAPIInclude annotation in RestComponent.

"build time" means that the micronaut annotation processor will discover classes annotated with io.micronaut.http.annotation.Controller and register them as request handlers at server bootstrap. This is done by default but it is always possible to register request handlers at runtime.

Why micronaut

Here is a discussion about adding 3rd party dependencies (micronaut and swagger). The main advantages of micronaut:

• Netty based
• Has a huge community 
• Supports security out-of-the-box

The last point is important. Ignite 3 will definitely need to implement security protocols and strategies. Micronaut already has implementations for the most popular ones (OAuth2/OpenID, LDAP, etc), they are tested in production by a community and have a little chance to introduce a vulnerability to the server compering with our own implementation. All these standards are going to be implemented in Ignite 3.

Implementation example

@OpenAPIDefinition(
        info = @Info(
                title = "Ignite REST module",
                version = "3.0.0-alpha",
                license = @License(name = "Apache 2.0", url = "https://ignite.apache.org"),
                contact = @Contact(email = "dev@ignite.apache.org")
        )
)
@OpenAPIInclude(classes = {ClusterConfigurationController.class, NodeConfigurationController.class}) // include to openapi specification
public class RestComponent implements IgniteComponent {
    // ...

    public RestComponent(List<MicronautFactory> micronautFactories, RestConfiguration restConfiguration) {
        // register all factories in micronaut context
    }

    @Override
    public void start() {
       // start REST server
    }

...

API

Configuration REST API

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

Management REST API

Manage cluster state.

Meta storage and cmg definitions.

Topology REST API

Provide information about cluster topology.

Version REST API

Provide the build version for the node. 

...