From 74a89dfa224f543a0bf932612493792de1d8f6d6 Mon Sep 17 00:00:00 2001 From: Alexey Timin Date: Wed, 2 Oct 2024 10:36:23 +0200 Subject: [PATCH 1/2] move swagger descriptions to md sections --- docs/http-api/bucket-api.mdx | 83 +++++++++++++------------- docs/http-api/replication-api.mdx | 78 ++++++++++++------------ docs/http-api/server-api.mdx | 51 ++++++---------- docs/http-api/token-authentication.mdx | 75 +++++++++++------------ 4 files changed, 136 insertions(+), 151 deletions(-) diff --git a/docs/http-api/bucket-api.mdx b/docs/http-api/bucket-api.mdx index f2ac3086..f8a559e2 100644 --- a/docs/http-api/bucket-api.mdx +++ b/docs/http-api/bucket-api.mdx @@ -24,19 +24,19 @@ Before starting to record data, a user must first create a bucket and specify se - Quota type - Quota size -For more information about buckets, read the [**how-does-it-work page**](../how-does-it-work.mdx#internal-structure). +For more information about buckets, read the [**Bucket Guide**](../guides/buckets). + +## Get Information about a Bucket + +The method returns the current settings, stats, and entry list of the +bucket in JSON format. + +If authentication is enabled, the method needs a valid API token. - The method returns the current settings, stats, and entry list of the - bucket in JSON format. If authentication is enabled, the method needs a - valid API token. - - } parameters={[ { type: "path", @@ -98,13 +98,14 @@ For more information about buckets, read the [**how-does-it-work page**](../how- ]} /> +## Check if a Bucket Exists + +If authentication is enabled, the method needs a valid API token. + If authentication is enabled, the method needs a valid API token. - } parameters={[ { type: "path", @@ -134,21 +135,19 @@ For more information about buckets, read the [**how-does-it-work page**](../how- ]} /> +## Create a New Bucket + +To create a bucket, the request should contain a JSON document with some +parameters or empty body. The new bucket uses default values if some +parameters are empty. + +If authentication is enabled, the method needs a valid API token with full +access. + - To create a bucket, the request should contain a JSON document with some - parameters or empty body. The new bucket uses default values if some - parameters are empty. -
-
- If authentication is enabled, the method needs a valid API token with full - access. - - } parameters={[ { type: "path", @@ -181,7 +180,7 @@ For more information about buckets, read the [**how-does-it-work page**](../how- details: { name: "quota_type", description: - "Type of quota. Can have values 'NONE' or FIFO (default: NONE)", + "Type of quota. Can have values 'NONE', FIFO or HARD (default: NONE)", dataType: "String", isRequired: false, }, @@ -225,20 +224,17 @@ For more information about buckets, read the [**how-does-it-work page**](../how- ]} /> +## Change Settings of a Bucket + + To update settings of a bucket, the request should have a JSON document + with all the settings. + +If authentication is enabled, the method needs a valid API token with full access. + - To update settings of a bucket, the request should have a JSON document - with all the settings. -
-
- If authentication is enabled, the method needs a valid API token with full - access. - - } parameters={[ { type: "path", @@ -319,19 +315,22 @@ For more information about buckets, read the [**how-does-it-work page**](../how- ]} /> +## Remove a Bucket + +Remove a bucket with all its entries and stored data. + +If authentication is enabled, the method needs a valid API token with full +access. + + +:::danger +This operation is irreversible. All data in the bucket will be lost. +::: + - Remove a bucket with all its entries and stored data. -
-
- If authentication is enabled, the method needs a valid API token with full - access. - - } parameters={[ { type: "path", diff --git a/docs/http-api/replication-api.mdx b/docs/http-api/replication-api.mdx index 0ae95462..9c3929cd 100644 --- a/docs/http-api/replication-api.mdx +++ b/docs/http-api/replication-api.mdx @@ -15,21 +15,23 @@ import SwaggerComponent from "@site/src/components/SwaggerComponent"; # Replication API Specification Reference -:::info Since version 1.8.0, ReductStore supports append-only replication. This feature allows replicating data from one bucket to another. -The replication is performed in the background and doesn't affect the performance of the main database. -::: + +For more information about replications, read the [**Replication Guide**](../guides/data-replication). + + + + +## Get a List of Replication Tasks + +The method returns a list of replication Task with their statuses. + +To use this method, you need an access token with full access. - The method returns a list of replications with their statuses. To use this - method, you need an access token with full access. - - } + summary="Get a list of replication tasks" responses={[ { status: "200", @@ -62,16 +64,17 @@ The replication is performed in the background and doesn't affect the performanc ]} /> +## Show Information about a Replication Task + +This method provides complete information about a replication task, including +diagnostics. + +This method requires a full access token. + - This method provides complete information about a replication, including - diagnostics. This method requires a full access token. - - } + summary="Show information about a replication task" parameters={[ { type: "path", @@ -144,16 +147,16 @@ The replication is performed in the background and doesn't affect the performanc ]} /> +## Create a New Replication Task + +The method creates a replication task with given settings. + +To use this method, you need an access token with full access. + - The method creates a replication with given settings. To use this method, - you need an access token with full access. - - } + summary="Create a new replication tasl" parameters={[ { type: "path", @@ -279,16 +282,15 @@ The replication is performed in the background and doesn't affect the performanc ]} /> +## Update an Existing Replication Task + + The method updates an existing replication task with given settings. To use + this method, you need an access token with full access. + - The method updates an existing replication with given settings. To use - this method, you need an access token with full access. - - } + summary="Update an existing replication task" parameters={[ { type: "path", @@ -419,16 +421,16 @@ The replication is performed in the background and doesn't affect the performanc ]} /> +## Delete a Replication Task + +The method deletes a replication task. + +To use this method, you need an access token with full access. + - The method deletes a replication. To use this method, you need an access - token with full access. - - } + summary="Delete a replication task" parameters={[ { type: "path", diff --git a/docs/http-api/server-api.mdx b/docs/http-api/server-api.mdx index 84bf7500..1ad0384d 100644 --- a/docs/http-api/server-api.mdx +++ b/docs/http-api/server-api.mdx @@ -17,21 +17,17 @@ import SwaggerComponent from "@site/src/components/SwaggerComponent"; The server API provides HTTP methods for checking the status of the server, listing the available buckets, and retrieving the permissions for the current API token. +## Get Statistical Information about Instance + +You can use this method to get stats of the storage, check its version and +license. + +If authentication is enabled, the method needs a valid API token. + - You can use this method to get stats of the storage, check its version and - license. If authentication is enabled, the method needs a valid API token. - 
-        
-          {`curl --header "authorsization: Bearer \${API_TOKEN}" http://127.0.0.1:8383/api/v1/info`}
-        
-
- - } responses={[ { status: "200", @@ -61,7 +57,7 @@ The server API provides HTTP methods for checking the status of the server, list "bucket":{ // default settings for a new bucket "max_block_size": "integer", // max block content_length in bytes "max_block_records": "integer", // max number of records in a block - "quota_type": Union["NONE", "FIFO"], // quota type + "quota_type": Union["NONE", "FIFO", "HARD"], // quota type "quota_size": "integer" // quota content_length in bytes } }`} @@ -79,21 +75,16 @@ The server API provides HTTP methods for checking the status of the server, list ]} /> +## Get a Bucket List with Metadata + +You can use this method to browse the buckets of the storage. + +If authentication is enabled, the method needs a valid API token. + - You can use this method to browse the buckets of the storage. If - authentication is enabled, the method needs a valid API token. - 
-        
-          {`curl --header "authorsization: Bearer \${API_TOKEN}" http://127.0.0.1:8383/api/v1/list`}
-        
-
- - } responses={[ { status: "200", @@ -127,19 +118,15 @@ The server API provides HTTP methods for checking the status of the server, list ]} /> +## Check if the Storage Engine is Alive + +You can use this method for health checks in Docker or Kubernetes +environment. The method has anonymous access. + - You can use this method for health checks in Docker or Kubernetes - environment. The method has anonymous access. - 
-        {`curl --head http://127.0.0.1:8383/api/v1/alive`}
-
- - } responses={[ { status: "200", diff --git a/docs/http-api/token-authentication.mdx b/docs/http-api/token-authentication.mdx index 6d90d1d9..ed3c18e3 100644 --- a/docs/http-api/token-authentication.mdx +++ b/docs/http-api/token-authentication.mdx @@ -15,20 +15,22 @@ import SwaggerComponent from "@site/src/components/SwaggerComponent"; # Token API Specification Reference +The Token API provides HTTP methods for managing access tokens and permissions for the database. + + :::info -The database uses the token authentication when the RS_API_TOKEN environment is set. You should use it as a full access token to create other tokens with different permission by using the Token API +The API is available only when the `RS_API_TOKEN` environment variable is set. ::: +## Get a List of Tokens + +The method returns a list of tokens with names and creation dates. To use +this method, you need an access token with full access. + - The method returns a list of tokens with names and creation dates. To use - this method, you need an access token with full access. - - } responses={[ { status: "200", @@ -59,16 +61,15 @@ The database uses the token authentication when the RS_API_TOKEN environment is ]} /> +## Show Information about a Token + +This method provides full information about a token except its values. The +method requires an access token with full access. + - This method provides full information about a token except its values. The - method requires an access token with full access. - - } parameters={[ { type: "path", @@ -116,17 +117,16 @@ The database uses the token authentication when the RS_API_TOKEN environment is ]} /> +## Create a New Token + +The method creates a new access token with given permissions as a JSON +document in the request body. To use this method, you need an access token +with full access. + - The method creates a new access token with given permissions as a JSON - document in the request body. To use this method, you need an access token - with full access. - - } parameters={[ { type: "path", @@ -202,17 +202,16 @@ The database uses the token authentication when the RS_API_TOKEN environment is ]} /> +## Update a Token + +The method updates an access token with given permissions as a JSON +document in the request body. To use this method, you need an access token +with full access. + - The method updates an access token with given permissions as a JSON - document in the request body. To use this method, you need an access token - with full access. - - } parameters={[ { type: "path", @@ -288,16 +287,15 @@ The database uses the token authentication when the RS_API_TOKEN environment is ]} /> +## Remove a Token + +This method removes or revokes a token. To use it, a client should have an +access token with full access. + - This method removes or revokes a token. To use it, a client should have an - access token with full access. - - } parameters={[ { type: "path", @@ -337,16 +335,15 @@ The database uses the token authentication when the RS_API_TOKEN environment is ]} /> +## Get Full Information about Current API Token + +This method takes a token from the Authentication header and returns its +name, permissions, and additional information. + - This method takes a token from the Authentication header and returns its - name, permissions, and additional information. - - } responses={[ { status: "200", From 4f4a387273e5ba3fa19f6aad48cca7ed744f3805 Mon Sep 17 00:00:00 2001 From: Alexey Timin Date: Thu, 3 Oct 2024 10:02:43 +0200 Subject: [PATCH 2/2] fmt --- docs/http-api/bucket-api.mdx | 5 ++--- docs/http-api/replication-api.mdx | 7 ++----- docs/http-api/server-api.mdx | 2 +- docs/http-api/token-authentication.mdx | 1 - 4 files changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/http-api/bucket-api.mdx b/docs/http-api/bucket-api.mdx index f8a559e2..29e99ee7 100644 --- a/docs/http-api/bucket-api.mdx +++ b/docs/http-api/bucket-api.mdx @@ -226,8 +226,8 @@ access. ## Change Settings of a Bucket - To update settings of a bucket, the request should have a JSON document - with all the settings. +To update settings of a bucket, the request should have a JSON document +with all the settings. If authentication is enabled, the method needs a valid API token with full access. @@ -322,7 +322,6 @@ Remove a bucket with all its entries and stored data. If authentication is enabled, the method needs a valid API token with full access. - :::danger This operation is irreversible. All data in the bucket will be lost. ::: diff --git a/docs/http-api/replication-api.mdx b/docs/http-api/replication-api.mdx index 9c3929cd..ff443352 100644 --- a/docs/http-api/replication-api.mdx +++ b/docs/http-api/replication-api.mdx @@ -19,9 +19,6 @@ Since version 1.8.0, ReductStore supports append-only replication. This feature For more information about replications, read the [**Replication Guide**](../guides/data-replication). - - - ## Get a List of Replication Tasks The method returns a list of replication Task with their statuses. @@ -284,8 +281,8 @@ To use this method, you need an access token with full access. ## Update an Existing Replication Task - The method updates an existing replication task with given settings. To use - this method, you need an access token with full access. +The method updates an existing replication task with given settings. To use +this method, you need an access token with full access. -## Get a Bucket List with Metadata +## Get a Bucket List with Metadata You can use this method to browse the buckets of the storage. diff --git a/docs/http-api/token-authentication.mdx b/docs/http-api/token-authentication.mdx index ed3c18e3..b6d820e0 100644 --- a/docs/http-api/token-authentication.mdx +++ b/docs/http-api/token-authentication.mdx @@ -17,7 +17,6 @@ import SwaggerComponent from "@site/src/components/SwaggerComponent"; The Token API provides HTTP methods for managing access tokens and permissions for the database. - :::info The API is available only when the `RS_API_TOKEN` environment variable is set. :::