Deuxfleurs/garage
33
58
Fork 80
Code Issues 101 Pull requests 18 Releases 30 Wiki Activity

admin api: update v2 openapi spec
Some checks failed
ci/woodpecker/push/debug Pipeline failed
Details
ci/woodpecker/pr/debug Pipeline failed
Details

Browse source
This commit is contained in:
Alex 2025-01-28 17:56:30 +01:00
parent 3b0c190b08
commit 7719f6a5b1
2 changed files with 143 additions and 112 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
doc/api/garage-admin-v2.html Normal file
View file

@ -0,0 +1,24 @@
<!DOCTYPE html>
<html>
<head>
<title>Garage Adminstration API v0</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="./css/redoc.css" rel="stylesheet">
<!--
Redoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='./garage-admin-v2.yml'></redoc>
<script src="./redoc.standalone.js"> </script>
</body>
</html>

175
doc/api/garage-admin-v2.yml
View file

@ -1,17 +1,17 @@
openapi: 3.0.0 openapi: 3.0.0
info: info:
version: v0.9.0 version: v2.0.0
title: Garage Administration API v0+garage-v0.9.0 title: Garage Administration API v0+garage-v2.0.0
description: | description: |
Administrate your Garage cluster programatically, including status, layout, keys, buckets, and maintainance tasks. Administrate your Garage cluster programatically, including status, layout, keys, buckets, and maintainance tasks.
*Disclaimer: The API is not stable yet, hence its v0 tag. The API can change at any time, and changes can include breaking backward compatibility. Read the changelog and upgrade your scripts before upgrading. Additionnaly, this specification is very early stage and can contain bugs, especially on error return codes/types that are not tested yet. Do not expect a well finished and polished product!* *Disclaimer: This API may change in future Garage versions. Read the changelog and upgrade your scripts before upgrading. Additionnaly, this specification is very early stage and can contain bugs, especially on error return codes/types that are not tested yet. Do not expect a well finished and polished product!*
paths: paths:
/health: /GetClusterHealth:
get: get:
tags: tags:
- Nodes - Nodes
operationId: "GetHealth" operationId: "GetClusterHealth"
summary: "Cluster health report" summary: "Cluster health report"
description: | description: |
Returns the global status of the cluster, the number of connected nodes (over the number of known ones), the number of healthy storage nodes (over the declared ones), and the number of healthy partitions (over the total). Returns the global status of the cluster, the number of connected nodes (over the number of known ones), the number of healthy storage nodes (over the declared ones), and the number of healthy partitions (over the total).
@ -59,11 +59,11 @@ paths:
type: integer type: integer
format: int64 format: int64
example: 256 example: 256
/status: /GetClusterStatus:
get: get:
tags: tags:
- Nodes - Nodes
operationId: "GetNodes" operationId: "GetClusterStatus"
summary: "Describe cluster" summary: "Describe cluster"
description: | description: |
Returns the cluster's current status, including: Returns the cluster's current status, including:
@ -134,11 +134,11 @@ paths:
layout: layout:
$ref: '#/components/schemas/ClusterLayout' $ref: '#/components/schemas/ClusterLayout'
/connect: /ConnectClusterNodes:
post: post:
tags: tags:
- Nodes - Nodes
operationId: "AddNode" operationId: "ConnectClusterNodes"
summary: "Connect a new node" summary: "Connect a new node"
description: | description: |
Instructs this Garage node to connect to other Garage nodes at specified `<node_id>@<net_address>`. `node_id` is generated automatically on node start. Instructs this Garage node to connect to other Garage nodes at specified `<node_id>@<net_address>`. `node_id` is generated automatically on node start.
@ -184,11 +184,11 @@ paths:
nullable: true nullable: true
example: null example: null
/layout: /GetClusterLayout:
get: get:
tags: tags:
- Layout - Layout
operationId: "GetLayout" operationId: "GetClusterLayout"
summary: "Details on the current and staged layout" summary: "Details on the current and staged layout"
description: | description: |
Returns the cluster's current layout, including: Returns the cluster's current layout, including:
@ -196,7 +196,7 @@ paths:
- Staged changes to the cluster layout - Staged changes to the cluster layout
*Capacity is given in bytes* *Capacity is given in bytes*
*The info returned by this endpoint is a subset of the info returned by `GET /status`.* *The info returned by this endpoint is a subset of the info returned by `GET /GetClusterStatus`.*
responses: responses:
'500': '500':
description: | description: |
@ -211,13 +211,14 @@ paths:
schema: schema:
$ref: '#/components/schemas/ClusterLayout' $ref: '#/components/schemas/ClusterLayout'
/UpdateClusterLayout:
post: post:
tags: tags:
- Layout - Layout
operationId: "AddLayout" operationId: "UpdateClusterLayout"
summary: "Send modifications to the cluster layout" summary: "Send modifications to the cluster layout"
description: | description: |
Send modifications to the cluster layout. These modifications will be included in the staged role changes, visible in subsequent calls of `GET /layout`. Once the set of staged changes is satisfactory, the user may call `POST /layout/apply` to apply the changed changes, or `POST /layout/revert` to clear all of the staged changes in the layout. Send modifications to the cluster layout. These modifications will be included in the staged role changes, visible in subsequent calls of `GET /GetClusterHealth`. Once the set of staged changes is satisfactory, the user may call `POST /ApplyClusterLayout` to apply the changed changes, or `POST /RevertClusterLayout` to clear all of the staged changes in the layout.
Setting the capacity to `null` will configure the node as a gateway. Setting the capacity to `null` will configure the node as a gateway.
Otherwise, capacity must be now set in bytes (before Garage 0.9 it was arbitrary weights). Otherwise, capacity must be now set in bytes (before Garage 0.9 it was arbitrary weights).
@ -258,11 +259,11 @@ paths:
schema: schema:
$ref: '#/components/schemas/ClusterLayout' $ref: '#/components/schemas/ClusterLayout'
/layout/apply: /ApplyClusterLayout:
post: post:
tags: tags:
- Layout - Layout
operationId: "ApplyLayout" operationId: "ApplyClusterLayout"
summary: "Apply staged layout" summary: "Apply staged layout"
description: | description: |
Applies to the cluster the layout changes currently registered as staged layout changes. Applies to the cluster the layout changes currently registered as staged layout changes.
@ -310,11 +311,11 @@ paths:
$ref: '#/components/schemas/ClusterLayout' $ref: '#/components/schemas/ClusterLayout'
/layout/revert: /RevertClusterLayout:
post: post:
tags: tags:
- Layout - Layout
operationId: "RevertLayout" operationId: "RevertClusterLayout"
summary: "Clear staged layout" summary: "Clear staged layout"
description: | description: |
Clears all of the staged layout changes. Clears all of the staged layout changes.
@ -332,9 +333,9 @@ paths:
'400': '400':
description: "Invalid syntax or requested change" description: "Invalid syntax or requested change"
'200': '200':
description: "The staged layout has been cleared, you can start again sending modification from a fresh copy with `POST /layout`." description: "The staged layout has been cleared, you can start again sending modification from a fresh copy with `POST /UpdateClusterLayout`."
"/key?list": /ListKeys:
get: get:
tags: tags:
- Key - Key
@ -365,10 +366,12 @@ paths:
type: string type: string
name: name:
type: string type: string
/CreateKey:
post: post:
tags: tags:
- Key - Key
operationId: "AddKey" operationId: "CreateKey"
summary: "Create a new API key" summary: "Create a new API key"
description: | description: |
Creates a new API access key. Creates a new API access key.
@ -400,11 +403,11 @@ paths:
schema: schema:
$ref: '#/components/schemas/KeyInfo' $ref: '#/components/schemas/KeyInfo'
"/key": /GetKeyInfo:
get: get:
tags: tags:
- Key - Key
operationId: "GetKey" operationId: "GetKeyInfo"
summary: "Get key information" summary: "Get key information"
description: | description: |
Return information about a specific key like its identifiers, its permissions and buckets on which it has permissions. Return information about a specific key like its identifiers, its permissions and buckets on which it has permissions.
@ -452,7 +455,8 @@ paths:
schema: schema:
$ref: '#/components/schemas/KeyInfo' $ref: '#/components/schemas/KeyInfo'
delete: /DeleteKey:
post:
tags: tags:
- Key - Key
operationId: "DeleteKey" operationId: "DeleteKey"
@ -474,6 +478,7 @@ paths:
description: "The key has been deleted" description: "The key has been deleted"
/UpdateKey:
post: post:
tags: tags:
- Key - Key
@ -530,7 +535,7 @@ paths:
$ref: '#/components/schemas/KeyInfo' $ref: '#/components/schemas/KeyInfo'
/key/import: /ImportKey:
post: post:
tags: tags:
- Key - Key
@ -572,7 +577,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/KeyInfo' $ref: '#/components/schemas/KeyInfo'
"/bucket?list": /ListBuckets:
get: get:
tags: tags:
- Bucket - Bucket
@ -629,7 +634,7 @@ paths:
accessKeyId: accessKeyId:
type: string type: string
/bucket: /CreateBucket:
post: post:
tags: tags:
- Bucket - Bucket
@ -646,7 +651,6 @@ paths:
application/json: application/json:
schema: schema:
type: object type: object
required: [ ]
properties: properties:
globalAlias: globalAlias:
type: string type: string
@ -681,6 +685,8 @@ paths:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/BucketInfo' $ref: '#/components/schemas/BucketInfo'
/GetBucketInfo:
get: get:
tags: tags:
- Bucket - Bucket
@ -723,7 +729,8 @@ paths:
$ref: '#/components/schemas/BucketInfo' $ref: '#/components/schemas/BucketInfo'
delete: /DeleteBucket:
post:
tags: tags:
- Bucket - Bucket
operationId: "DeleteBucket" operationId: "DeleteBucket"
@ -747,12 +754,13 @@ paths:
description: "Bucket is not empty" description: "Bucket is not empty"
'404': '404':
description: "Bucket not found" description: "Bucket not found"
'204': '200':
description: Bucket has been deleted description: Bucket has been deleted
put: /UpdateBucket:
post:
tags: tags:
- Bucket - Bucket
operationId: "UpdateBucket" operationId: "UpdateBucket"
@ -785,7 +793,6 @@ paths:
application/json: application/json:
schema: schema:
type: object type: object
required: [ ]
properties: properties:
websiteAccess: websiteAccess:
type: object type: object
@ -827,11 +834,11 @@ paths:
schema: schema:
$ref: '#/components/schemas/BucketInfo' $ref: '#/components/schemas/BucketInfo'
/bucket/allow: /BucketAllowKey:
post: post:
tags: tags:
- Bucket - Bucket
operationId: "AllowBucketKey" operationId: "BucketAllowKey"
summary: "Allow key" summary: "Allow key"
description: | description: |
⚠️ **DISCLAIMER**: Garage's developers are aware that this endpoint has an unconventional semantic. Be extra careful when implementing it, its behavior is not obvious. ⚠️ **DISCLAIMER**: Garage's developers are aware that this endpoint has an unconventional semantic. Be extra careful when implementing it, its behavior is not obvious.
@ -887,11 +894,11 @@ paths:
schema: schema:
$ref: '#/components/schemas/BucketInfo' $ref: '#/components/schemas/BucketInfo'
/bucket/deny: /BucketDenyKey:
post: post:
tags: tags:
- Bucket - Bucket
operationId: "DenyBucketKey" operationId: "BucketDenyKey"
summary: "Deny key" summary: "Deny key"
description: | description: |
⚠️ **DISCLAIMER**: Garage's developers are aware that this endpoint has an unconventional semantic. Be extra careful when implementing it, its behavior is not obvious. ⚠️ **DISCLAIMER**: Garage's developers are aware that this endpoint has an unconventional semantic. Be extra careful when implementing it, its behavior is not obvious.
@ -947,27 +954,28 @@ paths:
schema: schema:
$ref: '#/components/schemas/BucketInfo' $ref: '#/components/schemas/BucketInfo'
/bucket/alias/global: /GlobalAliasBucket:
put: post:
tags: tags:
- Bucket - Bucket
operationId: "PutBucketGlobalAlias" operationId: "GlobalAliasBucket"
summary: "Add a global alias" summary: "Add a global alias"
description: | description: |
Add a global alias to the target bucket Add a global alias to the target bucket
parameters: requestBody:
- name: id
in: query
required: true required: true
content:
application/json:
schema: schema:
type: object
required: [bucketId, alias]
properties:
bucketId:
type: string type: string
example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
- name: alias alias:
in: query
required: true
example: my_documents
schema:
type: string type: string
example: my_documents
responses: responses:
'500': '500':
description: "The server can not handle your request. Check your connectivity with the rest of the cluster." description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
@ -982,24 +990,26 @@ paths:
schema: schema:
$ref: '#/components/schemas/BucketInfo' $ref: '#/components/schemas/BucketInfo'
delete: /GlobalUnaliasBucket:
post:
tags: tags:
- Bucket - Bucket
operationId: "DeleteBucketGlobalAlias" operationId: "GlobalUnaliasBucket"
summary: "Delete a global alias" summary: "Delete a global alias"
description: | description: |
Delete a global alias from the target bucket Delete a global alias from the target bucket
parameters: requestBody:
- name: id
in: query
required: true required: true
content:
application/json:
schema: schema:
type: object
required: [bucketId, alias]
properties:
bucketId:
type: string type: string
example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
- name: alias alias:
in: query
required: true
schema:
type: string type: string
example: my_documents example: my_documents
responses: responses:
@ -1016,31 +1026,29 @@ paths:
schema: schema:
$ref: '#/components/schemas/BucketInfo' $ref: '#/components/schemas/BucketInfo'
/bucket/alias/local: /LocalAliasBucket:
put: post:
tags: tags:
- Bucket - Bucket
operationId: "PutBucketLocalAlias" operationId: "LocalAliasBucket"
summary: "Add a local alias" summary: "Add a local alias"
description: | description: |
Add a local alias, bound to specified account, to the target bucket Add a local alias, bound to specified account, to the target bucket
parameters: requestBody:
- name: id
in: query
required: true required: true
content:
application/json:
schema: schema:
type: object
required: [bucketId, accessKeyId, alias]
properties:
bucketId:
type: string type: string
example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
- name: accessKeyId accessKeyId:
in: query
required: true
schema:
type: string type: string
example: GK31c2f218a2e44f485b94239e example: GK31c2f218a2e44f485b94239e
- name: alias alias:
in: query
required: true
schema:
type: string type: string
example: my_documents example: my_documents
responses: responses:
@ -1057,31 +1065,30 @@ paths:
schema: schema:
$ref: '#/components/schemas/BucketInfo' $ref: '#/components/schemas/BucketInfo'
delete: /LocalUnaliasBucket:
post:
tags: tags:
- Bucket - Bucket
operationId: "DeleteBucketLocalAlias" operationId: "LocalUnaliasBucket"
summary: "Delete a local alias" summary: "Delete a local alias"
description: | description: |
Delete a local alias, bound to specified account, from the target bucket Delete a local alias, bound to specified account, from the target bucket
parameters: requestBody:
- name: id
in: query
required: true required: true
content:
application/json:
schema: schema:
type: object
required: [bucketId, accessKeyId, alias]
properties:
bucketId:
type: string type: string
example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
- name: accessKeyId accessKeyId:
in: query
schema:
type: string type: string
required: true
example: GK31c2f218a2e44f485b94239e example: GK31c2f218a2e44f485b94239e
- name: alias alias:
in: query
schema:
type: string type: string
required: true
example: my_documents example: my_documents
responses: responses:
'500': '500':
@ -1359,4 +1366,4 @@ security:
servers: servers:
- description: A local server - description: A local server
url: http://localhost:3903/v1/ url: http://localhost:3903/v2/