ID | IEP-87 |
Author | |
Sponsor | |
Created |
|
Status | DRAFT |
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).
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:
ignite-rest module will have additional dependencies:
any other module that wants to expose an enpoint:
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.
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.
@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 }
@Factory public class NodeConfigurationRestFactory implements MicronautFactory { // define all beans needed }
Here is an example of GET /management/v1/configuration/node endpoint (defined in configuration module):
@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();
This REST group provides methods to read and update node/cluster configuration.
Method | Path | Parameters | Description |
---|---|---|---|
GET | /management/v1/configuration/node/ | Return node configuration in HOCON format | |
GET | /management/v1/configuration/node/{configPath} |
| Return node configuration subtree in HOCON format specified with configPath parameter. |
PATCH | /management/v1/configuration/node/ |
| Update node configuration with a given body. |
GET | /management/v1/configuration/cluster/ | Return cluster configuration in HOCON format. | |
GET | /management/v1/configuration/cluster/{configPath} |
| Return cluster configuration subtree in HOCON format specified with configPath parameter. |
PATCH | /management/v1/configuration/cluster/ |
| Update cluster configuration with a given body. |
Manage cluster state.
Method | Path | Parameters | Description |
---|---|---|---|
POST | /management/v1/init/ |
| Initialize cluster |
Provide information about cluster topology.
Method | Path | Parameters | Description |
---|---|---|---|
GET | /management/v1/topology/ | Return cluster topology information(consistent ID, ID, address, status). |
Provide the build version for the node.
Method | Path | Parameters | Description |
---|---|---|---|
GET | /management/v1/version/ | Return node build version in semver format. |