aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/api/garage-admin-v0.yml267
1 files changed, 267 insertions, 0 deletions
diff --git a/doc/api/garage-admin-v0.yml b/doc/api/garage-admin-v0.yml
index 00250399..fa0ceb0e 100644
--- a/doc/api/garage-admin-v0.yml
+++ b/doc/api/garage-admin-v0.yml
@@ -455,6 +455,197 @@ paths:
application/json:
schema:
$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:
securitySchemes:
@@ -587,6 +778,82 @@ components:
owner:
type: boolean
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:
- bearerAuth: []