Update open-api.yml and removes cursor term mentions

meilisearch · Jun 1, 2022 · eed0178 · eed0178
1 parent e42bf44
commit eed0178
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 11 deletions.
diff --git a/open-api.yaml b/open-api.yaml
@@ -29,10 +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
-    after:
+    from:
       type: integer
-      description: Represents identifier to fetch the next slice of the results. The first item identifier for the next slice starts at `after+1`.
+      description: The first task uid returned.
       example: 999
+    next:
+      type: integer
+      description: Represents the value to send in `from` to fetch the next slice of the results. The first item for the next slice starts at this exact number. When the returned value is null, it means that all the data have been browsed in the given order.
+      example: 989
     timestamp:
       type: string
       description: An `RFC 3339` format for date/time/duration.
@@ -699,6 +703,12 @@ components:
       schema:
         type: number
         default: 0
+    from:
+      name: from
+      in: query
+      description: Fetch the next set of results from the given uid.
+      schema:
+        type: number
     q:
       name: q
       in: query
@@ -2892,12 +2902,15 @@ paths:
                       $ref: '#/components/schemas/task'
                   limit:
                     $ref: '#/components/schemas/limit'
-                  after:
-                    $ref: '#/components/schemas/after'
+                  from:
+                    $ref: '#/components/schemas/from'
+                  next:
+                    $ref: '#/components/schemas/next'
                 required:
                   - results
                   - limit
-                  - after
+                  - from
+                  - next
               examples:
                 Example:
                   value:
@@ -2932,9 +2945,12 @@ paths:
                         startedAt: '2021-01-01T09:38:02.000000Z'
                         finishedAt: '2021-01-01T09:38:07.000000Z'
                     limit: 2
-                    after: null
+                    from: 1
+                    next: null
       operationId: tasks.list
-      parameters: []
+      parameters:
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/from'
       security:
         - apiKey: []
   '/tasks/:taskUid':

diff --git a/text/0060-tasks-api.md b/text/0060-tasks-api.md
@@ -572,15 +572,15 @@ New task types are also added for these operations. `indexCreation`, `indexUpdat
 
 The API endpoints `/tasks` and `indexes/{indexUid}/tasks` are browsable using a keyset based pagination.
 
-##### 9.1 Why a keyset based pagination?
+##### 9.1 Why a Seek/Keyset based pagination?
 
 Keyset-based pagination is more appropriate when the data can grow or shrink quickly in terms of magnitude.
 
 ###### 9.1.1 Pros
 
 The performance is better than the not-so-good but old pagination with `offset`/`limit`.
 
-Cursor pagination keeps the results consistent between each page as the data evolves. It avoids the [Page Drift effect](https://use-the-index-luke.com/sql/partial-results/fetch-next-page), especially when the data is sorted from the most recent to the oldest.
+Seek/Keyset pagination keeps the results consistent between each page as the data evolves. It avoids the [Page Drift effect](https://use-the-index-luke.com/sql/partial-results/fetch-next-page), especially when the data is sorted from the most recent to the oldest.
 
 Moreover, the performance is superior to traditional pagination since the computational complexity remains constant to reach the identifier marking the beginning of the new slice to be returned from a hash table.
 
@@ -594,7 +594,7 @@ The main drawback of this type of pagination is that it does not navigate within
 |-------|------|--------------------------------------|
 | limit | integer  | Default `20`. |
 | from | integer | The first task uid returned |
-| next | integer - nullable  | Represents the query parameter to send to fetch the next slice of the results. The first item for the next slice starts at this exact number. When the returned value is null, it means that all the data have been browsed in the given order. |
+| next | integer - nullable  | Represents the value to send in `from` to fetch the next slice of the results. The first item for the next slice starts at this exact number. When the returned value is null, it means that all the data have been browsed in the given order. |
 
 ##### 9.3 GET query parameters
 
@@ -663,7 +663,7 @@ This part demonstrates keyset paging in action on `/tasks`, but it should be equ
 }
 ```
 
-**End of cursor pagination**
+**End of seek/keyset pagination**
 
 `GET` - `/tasks?from=20`
 
@@ -702,6 +702,11 @@ This part demonstrates keyset paging in action on `/tasks`, but it should be equ
 
 - If `from` is set with an out of bounds task `uid`, the response returns the tasks that are the nearest to the specified uid, the `next` field is set to the next page. It will be equivalent to call the `/tasks` route without any parameter.
 
+###### 9.5.3 Errors
+
+- 🔴 Sending a value with a different type than `Integer` for `limit` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error.
+- 🔴 Sending a value with a different type than `Integer` for `from` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error.
+
 ## 2. Technical details
 
 ### I. Measuring