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). 


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.

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, 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

ignite-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
  • 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:

  • 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:micronaut-context:jar:3.3.3
  • 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

NOTE: Modules that expose API do not include the micronaut-http-netty dependency.

Java code style changes

IMPORTANT: Additional dependencies here mean that Java Code Style Best Practices (3d party libraries) are going to be adjusted: Micrionaut for REST, Swagger for Open API annotations, and Micronaut serde for REST serialization.

Artifact management

The API specification is a new artifact that will be introduced during the build time. This file should be placed in the source code under modules/ignite-rest/openapi/openapi.yaml path.


Changes in API should not introduce breaking changes for the clients and the API version won't change. In case the breaking change is necessary, then new openapi-v2.yaml should be generated. 

openapi.yaml file versionning

Note that an Open API spec has a version field itself. This field is the specification file version but not the API version. The minor value should be incremented when any backward compatible change is introduced. The major value should be incremented when the breaking change is introduced.

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:

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

        info = @Info(
                title = "Ignite REST module",
                version = "3.0.0-alpha",
                license = @License(name = "Apache 2.0", url = ""),
                contact = @Contact(email = "")
@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

    public void start() {
       // start REST server
public class NodeConfigurationRestFactory implements MicronautFactory {
  // define all beans needed 

Here is an example of GET /management/v1/configuration/node endpoint (defined in configuration module): 

@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")
   public String getConfiguration() {
       return …;

Run this command to generate the specification:

Open API spec generation command
mvn -pl modules/rest -am clean package -DskipTests=true 

The specification generated:

   - nodeConfiguration
   summary: Returns node configuration in HOCON format.
   description: Returns node configuration in HOCON format.
   operationId: getNodeConfiguration
   parameters: []
       description: Whole node configuration
             type: string

To build the java client run:

Java client generation command
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();


Configuration REST API

Configuration API already exists in Apache Ignite 3.

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

Return node configuration in HOCON format
  • configPath: subtree selector in format root.subtree.subsubtree

Return node configuration subtree in HOCON format specified with configPath parameter.

  • request body: configuration to patch in HOCON format
Patch node configuration with a given body.
Return cluster configuration in HOCON format.
  • configPath: subtree selector in format root.subtree.subsubtree

Return cluster configuration subtree in HOCON format specified with configPath parameter.

  • request body: configuration to patch in HOCON format

Patch cluster configuration with a given body.

Management REST API

Management API already exists in Apache Ignite 3.

Manage cluster state.

  • body: list of meta storage node names and list of cmg nodes
Initialize cluster

Meta storage and cmg definitions.

Topology REST API

Provide information about cluster topology.


Return physical cluster topology information(consistent ID, ID, address, status).


Return logical cluster topology information(consistent ID, ID, address, status).

Version REST API

Provide the build version for the node. 


Return node build version in semver format.

Open tickets

T Key Summary Assignee Reporter P Status Resolution Created Updated Due

Closed tickets

T Key Summary Assignee Reporter P Status Resolution Created Updated Due

  • No labels