diff options
| -rw-r--r-- | doc/api/garage-admin-v1.yml | 125 |
1 files changed, 41 insertions, 84 deletions
diff --git a/doc/api/garage-admin-v1.yml b/doc/api/garage-admin-v1.yml index 21922da9..52b2faae 100644 --- a/doc/api/garage-admin-v1.yml +++ b/doc/api/garage-admin-v1.yml @@ -283,7 +283,7 @@ paths: '200': description: "The staged layout has been cleared, you can start again sending modification from a fresh copy with `POST /layout`." - /key: + "/key?list": get: tags: - Key @@ -349,7 +349,7 @@ paths: schema: $ref: '#/components/schemas/KeyInfo' - "/key?id={access_key}": + "/key": get: tags: - Key @@ -357,16 +357,28 @@ paths: summary: "Get key information" description: | Return information about a specific key like its identifiers, its permissions and buckets on which it has permissions. + You can search by specifying the exact key identifier (`id`) or by specifying a pattern (`search`). For confidentiality reasons, the secret key is not returned by default: you must pass the `showSecretKey` query parameter to get it. parameters: - - name: access_key - in: path - required: true - description: "The exact API access key generated by Garage" + - name: id + in: query + description: | + The exact API access key generated by Garage. + + Incompatible with `search`. example: "GK31c2f218a2e44f485b94239e" schema: type: string + - name: search + in: query + description: | + A pattern (beginning or full string) corresponding to a key identifier or friendly name. + + Incompatible with `id`. + example: "test-k" + schema: + type: string - name: showSecretKey in: query schema: @@ -464,43 +476,6 @@ paths: $ref: '#/components/schemas/KeyInfo' - "/key?search={pattern}": - get: - tags: - - Key - operationId: "SearchKey" - summary: "Select key by pattern" - description: | - Find the first key matching the given pattern based on its identifier or friendly name and return its information. - - For confidentiality reasons, the secret key is not returned by default: you must pass the `showSecretKey` query parameter to get it. - parameters: - - name: pattern - in: path - required: true - description: "A pattern (beginning or full string) corresponding to a key identifier or friendly name" - example: "test-k" - schema: - type: string - - name: showSecretKey - in: query - schema: - type: boolean - default: false - example: true - required: false - description: "Wether or not the secret key should be returned in the response" - responses: - '500': - description: "The server can not handle your request. Check your connectivity with the rest of the cluster." - '200': - description: | - Returns information about the key - content: - application/json: - schema: - $ref: '#/components/schemas/KeyInfo' - /key/import: post: tags: @@ -543,7 +518,7 @@ paths: schema: $ref: '#/components/schemas/KeyInfo' - /bucket: + "/bucket?list": get: tags: - Bucket @@ -599,6 +574,8 @@ paths: type: string accessKeyId: type: string + + /bucket: post: tags: - Bucket @@ -650,27 +627,35 @@ paths: application/json: schema: $ref: '#/components/schemas/BucketInfo' - - - "/bucket?id={bucket_id}": get: tags: - Bucket operationId: "GetBucketInfo" summary: "Get a bucket" description: | - Given a bucket identifier, get its information. + Given a bucket identifier (`id`) or a global alias (`alias`), 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" + - name: id + in: query + description: | + The exact bucket identifier, a 32 bytes hexadecimal string. + + Incompatible with `alias`. example: "b4018dc61b27ccb5c64ec1b24f53454bbbd180697c758c4d47a22a8921864a87" schema: type: string + - name: alias + in: query + description: | + The exact global alias of one of the existing buckets. + + Incompatible with `id`. + example: "my_documents" + schema: + type: string responses: '500': description: "The server can not handle your request. Check your connectivity with the rest of the cluster." @@ -694,8 +679,8 @@ paths: **Warning:** this will delete all aliases associated with the bucket! parameters: - - name: bucket_id - in: path + - name: id + in: query required: true description: "The exact bucket identifier, a 32 bytes hexadecimal string" example: "b4018dc61b27ccb5c64ec1b24f53454bbbd180697c758c4d47a22a8921864a87" @@ -731,8 +716,8 @@ paths: 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. parameters: - - name: bucket_id - in: path + - name: id + in: query required: true description: "The exact bucket identifier, a 32 bytes hexadecimal string" example: "b4018dc61b27ccb5c64ec1b24f53454bbbd180697c758c4d47a22a8921864a87" @@ -788,34 +773,6 @@ paths: schema: $ref: '#/components/schemas/BucketInfo' - "/bucket?globalAlias={alias}": - get: - tags: - - Bucket - operationId: "FindBucketInfo" - summary: "Find a bucket" - description: | - Find a bucket by its global alias - parameters: - - name: alias - in: path - required: true - description: "The exact global alias of one of the existing buckets" - example: "my_documents" - 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' - /bucket/allow: post: tags: |