From 8ef42c9609bcefc642cc9739acb921dffba49b89 Mon Sep 17 00:00:00 2001
From: Alex Auvolat <alex@adnab.me>
Date: Wed, 14 Jun 2023 17:13:41 +0200
Subject: admin docs: reformatting, key admin: add check

---
 doc/drafts/admin-api.md | 83 ++++++++++++++++++++++++++-----------------------
 1 file changed, 44 insertions(+), 39 deletions(-)

(limited to 'doc/drafts')

diff --git a/doc/drafts/admin-api.md b/doc/drafts/admin-api.md
index cb491945..572595db 100644
--- a/doc/drafts/admin-api.md
+++ b/doc/drafts/admin-api.md
@@ -363,6 +363,7 @@ existing layout in the cluster.
 This returns the new cluster layout with all changes reverted,
 as returned by GetClusterLayout.
 
+
 ### Access key operations
 
 #### ListKeys `GET /v1/key`
@@ -384,37 +385,6 @@ Example response:
 ]
 ```
 
-#### CreateKey `POST /v1/key`
-
-Creates a new API access key.
-
-Request body format:
-
-```json
-{
-    "name": "NameOfMyKey"
-}
-```
-
-This returns the key info, including the created secret key,
-in the same format as the result of GetKeyInfo.
-
-#### ImportKey `POST /v1/key/import`
-
-Imports an existing API key.
-
-Request body format:
-
-```json
-{
-    "accessKeyId": "GK31c2f218a2e44f485b94239e",
-    "secretAccessKey": "b892c0665f0ada8a4755dae98baa3b133590e11dae3bcc1f9d769d67f16c3835",
-    "name": "NameOfMyKey"
-}
-```
-
-This returns the key info in the same format as the result of GetKeyInfo.
-
 #### GetKeyInfo `GET /v1/key?id=<acces key id>`
 #### GetKeyInfo `GET /v1/key?search=<pattern>`
 
@@ -490,9 +460,38 @@ Example response:
 }
 ```
 
-#### DeleteKey `DELETE /v1/key?id=<acces key id>`
+#### CreateKey `POST /v1/key`
 
-Deletes an API access key.
+Creates a new API access key.
+
+Request body format:
+
+```json
+{
+    "name": "NameOfMyKey"
+}
+```
+
+This returns the key info, including the created secret key,
+in the same format as the result of GetKeyInfo.
+
+#### ImportKey `POST /v1/key/import`
+
+Imports an existing API key.
+This will check that the imported key is in the valid format, i.e.
+is a key that could have been generated by Garage.
+
+Request body format:
+
+```json
+{
+    "accessKeyId": "GK31c2f218a2e44f485b94239e",
+    "secretAccessKey": "b892c0665f0ada8a4755dae98baa3b133590e11dae3bcc1f9d769d67f16c3835",
+    "name": "NameOfMyKey"
+}
+```
+
+This returns the key info in the same format as the result of GetKeyInfo.
 
 #### UpdateKey `POST /v1/key?id=<acces key id>`
 
@@ -516,6 +515,11 @@ The possible flags in `allow` and `deny` are: `createBucket`.
 
 This returns the key info in the same format as the result of GetKeyInfo.
 
+#### DeleteKey `DELETE /v1/key?id=<acces key id>`
+
+Deletes an API access key.
+
+
 ### Bucket operations
 
 #### ListBuckets `GET /v1/bucket`
@@ -644,12 +648,6 @@ or no alias at all.
 Technically, you can also specify both `globalAlias` and `localAlias` and that would create
 two aliases, but I don't see why you would want to do that.
 
-#### DeleteBucket `DELETE /v1/bucket?id=<bucket id>`
-
-Deletes a storage bucket. A bucket cannot be deleted if it is not empty.
-
-Warning: this will delete all aliases associated with the bucket!
-
 #### UpdateBucket `PUT /v1/bucket?id=<bucket id>`
 
 Updates configuration of the given bucket.
@@ -682,6 +680,13 @@ In `quotas`: new values of `maxSize` and `maxObjects` must both be specified, or
 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.
 
+#### DeleteBucket `DELETE /v1/bucket?id=<bucket id>`
+
+Deletes a storage bucket. A bucket cannot be deleted if it is not empty.
+
+Warning: this will delete all aliases associated with the bucket!
+
+
 ### Operations on permissions for keys on buckets
 
 #### BucketAllowKey `POST /v1/bucket/allow`
-- 
cgit v1.2.3