OpenAPI spec for admin API #379

Merged
lx merged 15 commits from ecosystem/openapi into main 2022-11-16 10:51:05 +00:00
Showing only changes of commit e7824faa17 - Show all commits

View file

@ -1,7 +1,7 @@
openapi: 3.0.0 openapi: 3.0.0
info: info:
version: v0.7.3 version: v0.8.0
title: Garage Administration API v0+garage-v0.7.3 title: Garage Administration API v0+garage-v0.8.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.
@ -726,9 +726,58 @@ paths:
operationId: "AllowBucketKey" operationId: "AllowBucketKey"
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.
Allows a key to do read/write/owner operations on a bucket. Allows a key to do read/write/owner operations on a bucket.
Flags in permissions which have the value true will be activated. Other flags will remain unchanged. Flags in permissions which have the value true will be activated. Other flags will remain unchanged (ie. they will keep their internal value).
For example, if you set read to true, the key will be allowed to read the bucket.
If you set it to false, the key will keeps its previous read permission.
If you want to disallow read for the key, check the DenyBucketKey operation.
requestBody:
description: |
Aliases to put on the new bucket
required: true
content:
application/json:
schema:
type: object
required: [ bucketId, accessKeyId, permissions ]
properties:
bucketId:
type: string
example: "e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b"
accessKeyId:
type: string
example: "GK31c2f218a2e44f485b94239e"
permissions:
type: object
required: [ read, write, owner ]
properties:
read:
type: boolean
example: true
write:
type: boolean
example: true
owner:
type: boolean
example: true
responses:
'500':
description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
'400':
description: "Bad request, check your request body"
'404':
description: "Bucket not found"
'200':
description: Returns exhaustive information about the bucket
content:
application/json:
schema:
$ref: '#/components/schemas/BucketInfo'
/bucket/deny: /bucket/deny:
post: post:
@ -737,10 +786,59 @@ paths:
operationId: "DenyBucketKey" operationId: "DenyBucketKey"
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.
Denies a key from doing read/write/owner operations on a bucket. Denies a key from doing read/write/owner operations on a bucket.
Flags in permissions which have the value true will be deactivated. Other flags will remain unchanged. Flags in permissions which have the value true will be deactivated. Other flags will remain unchanged.
For example, if you set read to true, the key will be denied from reading.
If you set read to false, the key will keep its previous permissions.
If you want the key to have the reading permission, check the AllowBucketKey operation.
requestBody:
description: |
Aliases to put on the new bucket
required: true
content:
application/json:
schema:
type: object
required: [ bucketId, accessKeyId, permissions ]
properties:
bucketId:
type: string
example: "e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b"
accessKeyId:
type: string
example: "GK31c2f218a2e44f485b94239e"
permissions:
type: object
required: [ read, write, owner ]
properties:
read:
type: boolean
example: true
write:
type: boolean
example: true
owner:
type: boolean
example: true
responses:
'500':
description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
'400':
description: "Bad request, check your request body"
'404':
description: "Bucket not found"
'200':
description: Returns exhaustive information about the bucket
content:
application/json:
schema:
$ref: '#/components/schemas/BucketInfo'
/bucket/alias/global: /bucket/alias/global:
put: put:
tags: tags:
@ -749,6 +847,28 @@ paths:
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:
- name: id
in: query
required: true
example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
- name: alias
in: query
required: true
example: my_documents
responses:
'500':
description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
'400':
description: "Bad request, check your request body"
'404':
description: "Bucket not found"
'200':
description: Returns exhaustive information about the bucket
content:
application/json:
schema:
$ref: '#/components/schemas/BucketInfo'
delete: delete:
tags: tags:
@ -757,6 +877,28 @@ paths:
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:
- name: id
in: query
required: true
example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
- name: alias
in: query
required: true
example: my_documents
responses:
'500':
description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
'400':
description: "Bad request, check your request body"
'404':
description: "Bucket not found"
'200':
description: Returns exhaustive information about the bucket
content:
application/json:
schema:
$ref: '#/components/schemas/BucketInfo'
/bucket/alias/local: /bucket/alias/local:
put: put:
@ -766,6 +908,32 @@ paths:
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:
- name: id
in: query
required: true
example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
- name: accessKeyId
in: query
required: true
example: GK31c2f218a2e44f485b94239e
- name: alias
in: query
required: true
example: my_documents
responses:
'500':
description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
'400':
description: "Bad request, check your request body"
'404':
description: "Bucket not found"
'200':
description: Returns exhaustive information about the bucket
content:
application/json:
schema:
$ref: '#/components/schemas/BucketInfo'
delete: delete:
tags: tags:
@ -774,6 +942,32 @@ paths:
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:
- name: id
in: query
required: true
example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
- name: accessKeyId
in: query
required: true
example: GK31c2f218a2e44f485b94239e
- name: alias
in: query
required: true
example: my_documents
responses:
'500':
description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
'400':
description: "Bad request, check your request body"
'404':
description: "Bucket not found"
'200':
description: Returns exhaustive information about the bucket
content:
application/json:
schema:
$ref: '#/components/schemas/BucketInfo'
components: components:
securitySchemes: securitySchemes: