Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RS-455: Move swagger descriptions to md sections #101

Merged
merged 2 commits into from
Oct 3, 2024
Merged

RS-455: Move swagger descriptions to md sections #101

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
74a89df
move swagger descriptions to md sections
atimin Oct 2, 2024
4f4a387
fmt
atimin Oct 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 40 additions & 42 deletions docs/http-api/bucket-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<SwaggerComponent
method="GET"
path="/api/v1/b/:bucket_name"
summary="Get information about a bucket"
description={
<>
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",
Expand Down Expand Up @@ -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.

<SwaggerComponent
method="HEAD"
path="/api/v1/b/:bucket_name"
summary="Check if a bucket exists"
description={
<>If authentication is enabled, the method needs a valid API token.</>
}
parameters={[
{
type: "path",
Expand Down Expand Up @@ -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.

<SwaggerComponent
method="POST"
path="/api/v1/b/:bucket_name"
summary="Create a new bucket"
description={
<>
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.
<br />
<br />
If authentication is enabled, the method needs a valid API token with full
access.
</>
}
parameters={[
{
type: "path",
Expand Down Expand Up @@ -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,
},
Expand Down Expand Up @@ -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.

<SwaggerComponent
method="PUT"
path="/api/v1/b/:bucket_name"
summary="Change settings of a bucket"
description={
<>
To update settings of a bucket, the request should have a JSON document
with all the settings.
<br />
<br />
If authentication is enabled, the method needs a valid API token with full
access.
</>
}
parameters={[
{
type: "path",
Expand Down Expand Up @@ -319,19 +315,21 @@ 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.
:::

<SwaggerComponent
method="DELETE"
path="/api/v1/b/:bucket_name"
summary="Remove a bucket"
description={
<>
Remove a bucket with <strong>all its entries and stored data.</strong>
<br />
<br />
If authentication is enabled, the method needs a valid API token with full
access.
</>
}
parameters={[
{
type: "path",
Expand Down
75 changes: 37 additions & 38 deletions docs/http-api/replication-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,21 +15,20 @@ 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.

<SwaggerComponent
method="GET"
path="/api/v1/replications"
summary="Get a list of replications"
description={
<>
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",
Expand Down Expand Up @@ -62,16 +61,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.

<SwaggerComponent
method="GET"
path="/api/v1/replications/:replication_name"
summary="Show information about a replication"
description={
<>
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",
Expand Down Expand Up @@ -144,16 +144,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.

<SwaggerComponent
method="POST"
path="/api/v1/replications/:replication"
summary="Create a new replication"
description={
<>
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",
Expand Down Expand Up @@ -279,16 +279,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.

<SwaggerComponent
method="PUT"
path="/api/v1/replications/:replication_name"
summary="Update an existing replication"
description={
<>
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",
Expand Down Expand Up @@ -419,16 +418,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.

<SwaggerComponent
method="DELETE"
path="/api/v1/replications/:replication_name"
summary="Delete a replication"
description={
<>
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",
Expand Down
51 changes: 19 additions & 32 deletions docs/http-api/server-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<SwaggerComponent
method="get"
path="/api/v1/info"
summary="Get statistical information about the storage"
description={
<>
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.
<pre>
<code>
{`curl --header "authorsization: Bearer \${API_TOKEN}" http://127.0.0.1:8383/api/v1/info`}
</code>
</pre>
</>
}
responses={[
{
status: "200",
Expand Down Expand Up @@ -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
}
}`}
Expand All @@ -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.

<SwaggerComponent
method="get"
path="/api/v1/list"
summary="Get a list of the buckets with their stats"
description={
<>
You can use this method to browse the buckets of the storage. If
authentication is enabled, the method needs a valid API token.
<pre>
<code>
{`curl --header "authorsization: Bearer \${API_TOKEN}" http://127.0.0.1:8383/api/v1/list`}
</code>
</pre>
</>
}
responses={[
{
status: "200",
Expand Down Expand Up @@ -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.

<SwaggerComponent
method="head"
path="/api/v1/alive"
summary="Check if the storage engine is working"
description={
<>
You can use this method for health checks in Docker or Kubernetes
environment. The method has anonymous access.
<pre>
<code>{`curl --head http://127.0.0.1:8383/api/v1/alive`}</code>
</pre>
</>
}
responses={[
{
status: "200",
Expand Down
Loading
Loading