Change how query parameters are handled

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: