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:
REST module will have additional dependencies:
TBD
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();
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. |
TBD
TDB