API Guideline - Return list of API resources under a results array (#…

…138) * Place list of documents under a results array on /documents * Add results array for indexes object list * Add the future of indexes pagination * Update open-api.yml * Fix typo * Apply suggestions from code review Co-authored-by: cvermand <[email protected]> * Add offset/limit pagination for indexes and API keys * Try to add multipe refs to a response object Co-authored-by: cvermand <[email protected]>
meilisearch · Jul 7, 2022 · bba69d4 · bba69d4
1 parent 65e7ace
commit bba69d4
Show file tree

Hide file tree

Showing 4 changed files with 286 additions and 54 deletions.
diff --git a/open-api.yaml b/open-api.yaml
@@ -29,6 +29,14 @@ components:
       type: integer
       description: Limit given for the query. If limit is not provided as a query parameter, this parameter displays the default limit value.
       example: 10
+    offset:
+      type: integer
+      description: Offset given for the query. If offset is not provided as a query parameter, this parameter displays the default offset value.
+      example: 0
+    total:
+      type: integer
+      description: Total number of browsable results using offset/limit parameters for the given resource.
+      example: 50
     from:
       type: integer
       description: The first task uid returned.
@@ -84,7 +92,7 @@ components:
         title: American Ninja 5
         poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
         overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
-        release_date: '1993-01-01'
+        release_date: 725846400
       description: 'A document made of attribute. The maximum number of attribute for a document is 65,535.'
     matchesPosition:
       type: object
@@ -106,13 +114,13 @@ components:
         title: American Ninja 5
         poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
         overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
-        release_date: '1993-01-01'
+        release_date: 725846400
         _formatted:
           id: 25684
           title: American Ninja 5
           poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
           overview: 'When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.'
-          release_date: '1993-01-01'
+          release_date: 725846400
         _matchesPosition:
           overview:
             - start: 49
@@ -124,13 +132,13 @@ components:
           title: American Ninja 5
           poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
           overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
-          release_date: '1993-01-01'
+          release_date: 725846400
           _formatted:
             id: 25684
             title: American Ninja 5
             poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
             overview: 'When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.'
-            release_date: '1993-01-01'
+            release_date: 725846400
           _matchesPosition:
             overview:
               - start: 49
@@ -675,14 +683,14 @@ components:
     limit:
       name: limit
       in: query
-      description: Maximum number of documents to return.
+      description: Maximum number of results to return.
       schema:
         type: number
         default: 20
     offset:
       name: offset
       in: query
-      description: Number of documents to skip.
+      description: Number of results to skip.
       schema:
         type: number
         default: 0
@@ -1014,19 +1022,40 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/index'
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/index'
+                  limit:
+                    $ref: '#/components/schemas/limit'
+                  offset:
+                    $ref: '#/components/schemas/offset'
+                  total:
+                    $ref: '#/components/schemas/total'
+                required:
+                  - results
+                  - limit
+                  - offset
+                  - total
               examples:
                 Example:
                   value:
-                    - uid: movies
-                      name: movies
-                      primaryKey: movie_id
-                      createdAt: '2019-11-20T09:40:33.711324Z'
-                      updatedAt: '2019-11-20T09:40:33.711324Z'
+                    results:
+                      - uid: movies
+                        name: movies
+                        primaryKey: movie_id
+                        createdAt: '2019-11-20T09:40:33.711324Z'
+                        updatedAt: '2019-11-20T09:40:33.711324Z'
+                    limit: 1
+                    offset: 0
+                    total: 1
         '401':
           $ref: '#/components/responses/401'
+      parameters:
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/offset'
     post:
       operationId: indexes.create
       summary: Create Index
@@ -1192,17 +1221,40 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/document'
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/document'
+                  limit:
+                    $ref: '#/components/schemas/limit'
+                  offset:
+                    $ref: '#/components/schemas/offset'
+                  total:
+                    $ref: '#/components/schemas/total'
+                required:
+                  - results
+                  - limit
+                  - offset
+                  - total
               examples:
                 Example:
                   value:
-                    - id: 25684
-                      title: American Ninja 5
-                      poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
-                      overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
-                      release_date: '1993-01-01'
+                    results:
+                      - id: 25684
+                        title: American Ninja 5
+                        poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
+                        overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
+                        release_date: 725846400
+                      - id: 45881
+                        title: The Bridge of San Luis Rey
+                        poster: 'https://image.tmdb.org/t/p/w500/4X7quIcdkc24Cveg5XdpfRqxtYA.jpg'
+                        overview: "The Bridge of San Luis Rey is American author Thornton Wilder's second novel, first published in 1927 to worldwide acclaim. It tells the story of several interrelated people who die in the collapse of an Inca rope-fiber suspension bridge in Peru, and the events that lead up to their being on the bridge.[ A friar who has witnessed the tragic accident then goes about inquiring into the lives of the victims, seeking some sort of cosmic answer to the question of why each had to die. The novel won the Pulitzer Prize in 1928."
+                        release_date: 1072915200
+                    limit: 20
+                    offset: 0
+                    total: 2
         '401':
           $ref: '#/components/responses/401'
         '404':
@@ -1290,7 +1342,7 @@ paths:
                     title: American Ninja 5
                     poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
                     overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
-                    release_date: '1993-01-01'
+                    release_date: 725846400
         description: ''
       responses:
         '202':
@@ -1446,13 +1498,13 @@ paths:
                         title: American Ninja 5
                         poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
                         overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
-                        release_date: '1993-01-01'
+                        release_date: 725846400
                         _formatted:
                           id: 25684
                           title: American Ninja 5
                           poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
                           overview: 'When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.'
-                          release_date: '1993-01-01'
+                          release_date: 725846400
                         _matchesPosition:
                           overview:
                             - start: 49
@@ -1588,13 +1640,13 @@ paths:
                         title: American Ninja 5
                         poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
                         overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
-                        release_date: '1993-01-01'
+                        release_date: 725846400
                         _formatted:
                           id: 25684
                           title: American Ninja 5
                           poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
                           overview: 'When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.'
-                          release_date: '1993-01-01'
+                          release_date: 725846400
                         _matchesPosition:
                           overview:
                             - start: 49
@@ -2502,6 +2554,17 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/key'
+                  limit:
+                    $ref: '#/components/schemas/limit'
+                  offset:
+                    $ref: '#/components/schemas/offset'
+                  total:
+                    $ref: '#/components/schemas/total'
+                required:
+                  - results
+                  - limit
+                  - offset
+                  - total
               examples:
                 example-1:
                   value:
@@ -2515,8 +2578,14 @@ paths:
                         expiresAt: '2022-11-12T10:00:00Z'
                         createdAt: '2021-11-12T10:00:00Z'
                         updatedAt: '2021-11-12T10:00:00Z'
+                    limit: 20
+                    offset: 0
+                    total: 1
         '401':
           $ref: '#/components/responses/401'
+      parameters:
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/offset'
   '/keys/{key}':
     get:
       summary: Get an API key

diff --git a/text/0085-api-keys.md b/text/0085-api-keys.md
@@ -367,8 +367,67 @@ Only the master key allows managing the API keys.
 ```
 "Authorization: Bearer :masterKey"
 ```
+##### Query Parameters
 
-##### Response
+| Field                    | Type                     | Required |
+|--------------------------|--------------------------|----------|
+| `offset`                 | Integer / `null`         | false    |
+| `limit`                  | Integer / `null`         | false    |
+
+###### `offset`
+
+- Type: Integer
+- Required: False
+- Default: `0`
+
+Sets the starting point in the results, effectively skipping over a given number of API keys.
+
+###### `limit`
+
+- Type: Integer
+- Required: False
+- Default: `20`
+
+Sets the maximum number of documents to be returned by the current request.
+
+##### Response Definition
+
+| Field                    | Type                     | Required |
+|--------------------------|--------------------------|----------|
+| `result`                 | Array[Key]               | true     |
+| `offset`                 | Integer                  | true     |
+| `limit`                  | Integer                  | true     |
+| `total`                  | Integer                  | true     |
+
+###### `results`
+
+- Type: Array[Key]
+- Required: True
+
+An array containing the fetched API keys.
+
+###### `offset`
+
+- Type: Integer
+- Required: True
+
+Gives the `offset` parameter used for the query.
+
+###### `limit`
+
+- Type: Integer
+- Required: True
+
+Gives the `limit` parameter used for the query.
+
+###### `total`
+
+- Type: Integer
+- Required: True
+
+Gives the total number of API keys that can be browsed.
+
+###### Example
 
 `200 Success`
 
@@ -416,7 +475,10 @@ Only the master key allows managing the API keys.
             "createdAt": "2021-08-11T10:00:00Z",
             "updatedAt": "2021-08-11T10:00:00Z"
         }
-    ]
+    ],
+    "offset": 0,
+    "limit": 20,
+    "total": 3
 }
 ```