This is an automated email from the ASF dual-hosted git repository.
sk0x50 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ignite-3.git
The following commit(s) were added to refs/heads/main by this push:
new 53896eb702 IGNITE-16969 Added developer documentation to REST modules.
Fixes #1028
53896eb702 is described below
commit 53896eb7024dafbfd008af21b4488c3bb7063b25
Author: Aleksandr Pakhomov <[email protected]>
AuthorDate: Tue Aug 30 09:58:32 2022 +0300
IGNITE-16969 Added developer documentation to REST modules. Fixes #1028
Signed-off-by: Slava Koptilin <[email protected]>
---
modules/README.md | 3 ++-
modules/rest-api/README.md | 31 +++++++++++++++++++++++++++
modules/rest/README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 85 insertions(+), 1 deletion(-)
diff --git a/modules/README.md b/modules/README.md
index a58e6aa5f7..7201ca4893 100644
--- a/modules/README.md
+++ b/modules/README.md
@@ -19,7 +19,8 @@ Module Name | Description
[core: causality
tokens](core/src/main/java/org/apache/ignite/internal/causality/README.md)|Causality
tokens
[core: local state
recovery](core/src/main/java/org/apache/ignite/internal/manager/RECOVERY.md)|Local
state recovery
[network](network/README.md)|Networking module: group membership and message
passi
-[rest](rest/README.md)|REST management endpoint bindings and command handlers
+[rest](rest/README.md)|REST server and Open API spec generation
+[rest-api](rest-api/README.md)|REST API interfaces
[runner](runner/README.md)|Ignite server node runner. The module that wires up
the Ignite components and handles node lifecycle.
[schema](schema/README.md)|Ignite schema API implementation and schema
management classes.
[table](table/README.md)|Ignite table API implementation.
diff --git a/modules/rest-api/README.md b/modules/rest-api/README.md
new file mode 100644
index 0000000000..9145937474
--- /dev/null
+++ b/modules/rest-api/README.md
@@ -0,0 +1,31 @@
+# ignite-rest-api
+
+This module defines REST APIs that might be provided by Ignite 3. Also, common
+DTOs and error handlers are defined.
+
+## API definition
+
+The API definition is a java interface annotated with micronaut `@Controller`
+annotations and several `swagger-annotations`. All those annotations are
+needed to generate a valid [Open API
spec](https://spec.openapis.org/oas/v3.1.0) from these interfaces.
+
+[ClusterManagementApi](src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterManagementApi.java)
is an example of API definition.
+
+## Error handling
+
+Ignite 3 implements the
[application/problem+json](https://www.rfc-editor.org/rfc/rfc7807.html) in all
endpoints. That's why
+problem definition and common problem handling are defined in this module.
Here is how it works:
+
+-
[`IgniteException`](../api/src/main/java/org/apache/ignite/lang/IgniteException.java)
is thrown in any Ignite component
+- REST Controller might not handle this exception
+-
[`IgniteExceptionHandler`](src/main/java/org/apache/ignite/internal/rest/exception/handler/IgniteExceptionHandler.java)
+is invoked by micronaut infrastructure
+-
[`IgniteExceptionHandler`](src/main/java/org/apache/ignite/internal/rest/exception/handler/IgniteExceptionHandler.java)
handles
+[`IgniteException`](../api/src/main/java/org/apache/ignite/lang/IgniteException.java)
and returns a valid `application/problem+json`
+
+> Make sure that
[`IgniteExceptionHandler`](src/main/java/org/apache/ignite/internal/rest/exception/handler/IgniteExceptionHandler.java)
+> has been loaded into micronaut context otherwise this class won't be invoked.
+
+If you want to implement your exception handler the best place to do it
+is the module where you define the REST controller. Don't put your handlers in
+`ignite-rest-api` unless it is needed for all REST endpoints.
diff --git a/modules/rest/README.md b/modules/rest/README.md
new file mode 100644
index 0000000000..36d494c32b
--- /dev/null
+++ b/modules/rest/README.md
@@ -0,0 +1,52 @@
+# ignite-rest
+
+This module defines
[RestComponent](src/main/java/org/apache/ignite/internal/rest/RestComponent.java)
that is responsible for:
+
+- aggregating all REST API definitions by `@OpenAPIInclude` annotation at
compile time
+- creating a micronaut context at runtime and injecting all needed beans into
the context
+- starting the micronaut server at the configured port range
+
+During the build time, the [Open API
spec](https://spec.openapis.org/oas/v3.1.0) is generated from all API
definitions that are included in
+`@OpenAPIInclude` annotation. The spec is located in `ignite-rest/openapi`.
+
+## How to create a new REST Endpoint
+
+- define API in `ignite-rest-api` module
+- link the API interface in `RestComponent`'s `@OpenAPIInclude` section
+- implement an API interface in the module that is responsible for the API
scope
+- define micronaut factory that is responsible for the creation of beans that
are needed for your Controller
+- for extending the exception handling mechanism, implement micronaut's
`ExceptionHandler` and include it in the micronaut factory
+- create the instance of the RestFactory in the IgniteImpl constructor and put
the factory to the RestComponent's constructor
+
+> The class that implements the API should be a valid micronaut controller.
+> Module with the API implementation should configure `micronaut-inject-java`
annotation processor.
+
+> Micronaut factories have to implement `RestFactory` from `ignite-rest-api`
+
+## Example of REST Endpoint
+
+- API definition
[ClusterManagementApi](../rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterManagementApi.java)
+- API implementation
[ClusterManagementController](../cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/rest/ClusterManagementController.java)
+- `RestFactory` implementation
[ClusterManagementRestFactory](../cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/rest/ClusterManagementRestFactory.java)
+- `ExceptionHandler` implementation
[ClusterNotInitializedExceptionHandler](../cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/rest/exception/handler/ClusterNotInitializedExceptionHandler.java)
+
+## Architecture of REST server
+
+`ignite-rest-api` module defines only API without any implementation.
+The main value of this module is to provide all needed information to generate
an Open API spec.
+
+REST server is started by
[RestComponent](src/main/java/org/apache/ignite/internal/rest/RestComponent.java)
in `ignite-rest` module.
+This module also configures `micronaut-openapi` generator and generates an
Open API spec during the build time.
+But the only dependency of the `ignite-rest` is `ignite-rest-api`. **There is
no dependency on any module that provides API implementation.**
+
+REST Controllers together with RestFactories are set to RestComponent at
runtime by IgniteImpl through the constructor.
+
+
+## How to test REST Endpoints
+
+Unit tests can be defined at the same module where the Controller is
implemented, see
[ClusterConfigurationControllerTest](../configuration/src/test/java/org/apache/ignite/internal/rest/configuration/ClusterConfigurationControllerTest.java).
+To make them work test dependencies should include `micronaut-test-junit5`,
`micronaut-http-client`, `micronaut-http-server-netty`.
+Also, `micronaut-inject-java` annotation processor should be configured.
+
+Integration tests could be defined in runner module, see
`ItInitializedClusterRestTest` and `ItNotInitializedClusterRestTest`.
+
