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 ebe8a41f2d - Show all commits

View file

@ -455,6 +455,197 @@ paths:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/KeyInfo' $ref: '#/components/schemas/KeyInfo'
/bucket:
get:
tags:
- Bucket
operationId: "ListBuckets"
summary: "List all buckets"
description: |
List all the buckets on the cluster with their UUID and their global and local aliases.
responses:
'500':
description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
'200':
description: |
Returns the UUID of the bucket and all its aliases
content:
application/json:
schema:
type: array
example:
- id: "70dc3bed7fe83a75e46b66e7ddef7d56e65f3c02f9f80b6749fb97eccb5e1033"
globalAliases:
- "container_registry"
- id: "96470e0df00ec28807138daf01915cfda2bee8eccc91dea9558c0b4855b5bf95"
localAliases:
- alias: "my_documents"
accessKeyid: "GK31c2f218a2e44f485b94239e"
- id: "d7452a935e663fc1914f3a5515163a6d3724010ce8dfd9e4743ca8be5974f995"
globalAliases:
- "example.com"
- "www.example.com"
localAliases:
- alias: "corp_website"
accessKeyId: "GKe10061ac9c2921f09e4c5540"
- alias: "web"
accessKeyid: "GK31c2f218a2e44f485b94239e"
- id: ""
items:
type: object
required: [ id ]
properties:
id:
type: string
globalAliases:
type: array
items:
type: string
localAliases:
type: array
items:
type: object
required: [ alias, accessKeyId ]
properties:
alias:
type: string
accessKeyId:
type: string
post:
tags:
- Bucket
operationId: "CreateBucket"
summary: "Create a bucket"
description: |
Create a bucket and set zero or more global or local alias.
"/bucket?id={bucket_id}":
get:
tags:
- Bucket
operationId: "GetBucketInfo"
summary: "Get a bucket"
description: |
Given a bucket identifier, get its information.
It includes its aliases, its web configuration, keys that have some permissions
on it, some statistics (number of objects, size), number of dangling multipart uploads,
and its quotas (if any).
parameters:
- name: bucket_id
in: path
required: true
description: "The exact bucket identifier, a 32 bytes hexadecimal string"
example: "b4018dc61b27ccb5c64ec1b24f53454bbbd180697c758c4d47a22a8921864a87"
schema:
type: string
responses:
'500':
description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
'404':
description: "Bucket not found"
'200':
description: Returns exhaustive information about the bucket
content:
application/json:
schema:
$ref: '#/components/schemas/BucketInfo'
delete:
tags:
- Bucket
operationId: "DeleteBucket"
summary: "Delete a bucket"
description: |
Delete a bucket.Deletes a storage bucket. A bucket cannot be deleted if it is not empty.
**Warning:** this will delete all aliases associated with the bucket!
put:
tags:
- Bucket
operationId: "UpdateBucket"
summary: "Update a bucket"
description: |
All fields (`websiteAccess` and `quotas`) are optionnal.
If they are present, the corresponding modifications are applied to the bucket, otherwise nothing is changed.
In `websiteAccess`: if `enabled` is `true`, `indexDocument` must be specified.
The field `errorDocument` is optional, if no error document is set a generic
error message is displayed when errors happen. Conversely, if `enabled` is
`false`, neither `indexDocument` nor `errorDocument` must be specified.
In `quotas`: new values of `maxSize` and `maxObjects` must both be specified, or set to `null`
to remove the quotas. An absent value will be considered the same as a `null`. It is not possible
to change only one of the two quotas.
"/bucket?globalAlias={alias}":
get:
tags:
- Bucket
operationId: "FindBucketInfo"
summary: "Find a bucket"
description: |
Find a bucket by its global alias
/bucket/allow:
post:
tags:
- Bucket
operationId: "AllowBucketKey"
summary: "Allow key"
description: |
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.
/bucket/deny:
post:
tags:
- Bucket
operationId: "DenyBucketKey"
summary: "Deny key"
description: |
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.
/bucket/alias/global:
put:
tags:
- Bucket
operationId: "PutBucketGlobalAlias"
summary: "Add a global alias"
description: |
Add a global alias to the target bucket
delete:
tags:
- Bucket
operationId: "DeleteBucketGlobalAlias"
summary: "Delete a global alias"
description: |
Delete a global alias from the target bucket
/bucket/alias/local:
put:
tags:
- Bucket
operationId: "PutBucketLocalAlias"
summary: "Add a local alias"
description: |
Add a local alias, bound to specified account, to the target bucket
delete:
tags:
- Bucket
operationId: "DeleteBucketLocalAlias"
summary: "Delete a local alias"
description: |
Delete a local alias, bound to specified account, from the target bucket
components: components:
securitySchemes: securitySchemes:
@ -587,6 +778,82 @@ components:
owner: owner:
type: boolean type: boolean
example: false example: false
BucketInfo:
type: object
properties:
id:
type: string
required: true
example: afa8f0a22b40b1247ccd0affb869b0af5cff980924a20e4b5e0720a44deb8d39
globalAliases:
type: array
items:
type: string
example: "my_documents"
websiteAccess:
type: bool
example: true
websiteConfig:
type: object
nullable: true
properties:
indexDocument:
type: string
example: "index.html"
errorDocument:
type: string
example: "error/400.html"
keys:
type: array
items:
$ref: '#/components/schemas/BucketKeyInfo'
objects:
type: integer
example: 14827
bytes:
type: integer
example: 13189855625
unfinishedUploads:
type: integer
example: 0
quotas:
type: object
properties:
maxSize:
nullable: true
type: integer
example: null
maxObjects:
nullable: true
type: integer
example: null
BucketKeyInfo:
type: object
properties:
accessKeyId:
type: string
name:
type: string
permissions:
type: object
properties:
read:
type: boolean
example: true
write:
type: boolean
example: true
owner:
type: boolean
example: true
bucketLocalAliases:
type: array
items:
type: string
example: "my_documents"
security: security:
- bearerAuth: [] - bearerAuth: []