From bba69d408a7be551fe77c41f8fbd8529fa3c2d1d Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 7 Jul 2022 13:19:27 +0200 Subject: [PATCH] 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 <33010418+bidoubiwa@users.noreply.github.com> * Add offset/limit pagination for indexes and API keys * Try to add multipe refs to a response object Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com> --- open-api.yaml | 125 ++++++++++++++++++++++++++++--------- text/0085-api-keys.md | 66 +++++++++++++++++++- text/0124-documents-api.md | 76 ++++++++++++++++------ text/0132-indexes-api.md | 73 ++++++++++++++++++++-- 4 files changed, 286 insertions(+), 54 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index cc6e9124..082e4516 100644 --- 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 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 _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 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 _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 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 _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 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 _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 index c85c6240..b14057ef 100644 --- 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 } ``` diff --git a/text/0124-documents-api.md b/text/0124-documents-api.md index c1d84a1d..3dc03f73 100644 --- a/text/0124-documents-api.md +++ b/text/0124-documents-api.md @@ -53,7 +53,7 @@ Unique identifier of an index. | Field | Type | Required | |--------------------------|--------------------------|----------| | `offset` | Integer / `null` | false | -| `limit` | String / `null` | false | +| `limit` | Integer / `null` | false | | `attributesToRetrieve` | String / `null` | false | ###### 3.1.1.2.1. `offset` @@ -88,27 +88,65 @@ If no value is specified, `attributesToRetrieve` uses the `displayedAttributes` ##### 3.1.1.3. Response Definition -An array of documents represented as JSON objects. +A `results` array representing documents as JSON objects. -###### 3.1.1.3.1. Example +| Field | Type | Required | +|--------------------------|--------------------------|----------| +| `results` | Array[Document] | true | +| `offset` | Integer | true | +| `limit` | Integer | true | +| `total` | Integer | true | + +###### 3.1.1.3.1. `results` + +- Type: Array[Document] +- Required: True + +An array containing the fetched documents. + +###### 3.1.1.3.2. `offset` + +- Type: Integer +- Required: True + +Gives the `offset` parameter used for the query. + +> See [3.1.1.2.1. `offset`](#31121-offset) section. + +###### 3.1.1.3.3. `limit` + +- Type: Integer +- Required: True + +Gives the `limit` parameter used for the query. + +> See [3.1.1.2.2. `limit`](#31122-limit) section. + +###### 3.1.1.3.3. `total` + +- Type: Integer +- Required: True + +Gives the total number of documents that can be browsed in the related index. + +###### 3.1.1.3.4. Example ```json -[ - { - "id": 25684, - "release_date": "1993-01-01", - "poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg", - "title": "American Ninja 5", - "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." - }, - { - "id": 468219, - "title": "Dead in a Week (Or Your Money Back)", - "release_date": "2018-09-12", - "poster": "https://image.tmdb.org/t/p/w1280/f4ANVEuEaGy2oP5M0Y2P1dwxUNn.jpg", - "overview": "William has failed to kill himself so many times that he outsources his suicide to aging assassin Leslie. But with the contract signed and death assured within a week (or his money back), William suddenly discovers reasons to live... However Leslie is under pressure from his boss to make sure the contract is completed." - } -] +{ + "results": [ + { + "id": 25684, + "title": "American Ninja 5" + }, + { + "id": 468219, + "title": "Dead in a Week (Or Your Money Back)" + } + ], + "offset": 0, + "limit": 2, + "total": 3 //The index contains 3 documents in total +} ``` ##### 3.1.1.4. Errors diff --git a/text/0132-indexes-api.md b/text/0132-indexes-api.md index 3420554f..a37a8fae 100644 --- a/text/0132-indexes-api.md +++ b/text/0132-indexes-api.md @@ -13,8 +13,6 @@ Indexes contain a set of documents in which to search and have their specific se See [Documents API specification](0124-documents-api.md) and [Settings API specification](0123-settings-api.md) for more details. -### 3.1. API Endpoints Definition - ### 3.1. `index` API Resource Definition @@ -98,9 +96,73 @@ Manipulate indexes of a Meilisearch instance. List all indexes of a Meilisearch instance. -##### 3.2.1.1. Response Definition +The results are sorted in ascending alphanumeric order from the `uid` field. + +##### 3.2.1.1. Query Parameters + +| Field | Type | Required | +|--------------------------|--------------------------|----------| +| `offset` | integer / `null` | false | +| `limit` | integer / `null` | false | + +###### 3.2.1.1.1. `offset` + +- Type: Integer +- Required: False +- Default: `0` + +Sets the starting point in the results, effectively skipping over a given number of indexes. + +###### 3.2.1.1.2. `limit` + +- Type: Integer +- Required: False +- Default: `20` + +Sets the maximum number of indexes to be returned by the current request. + +##### 3.2.1.2. Response Definition + +An object containing all the indexes. + +| Field | Type | Required | +|--------------------------|--------------------------|----------| +| `results` | Array[Index] | true | +| `offset` | integer | true | +| `limit` | integer | true | +| `total` | integer | true | + +###### 3.2.1.2.1. `results` + +- Type: Array[Index] +- Required: True + +An array containing the fetched indexes. + +###### 3.2.1.2.2. `offset` + +- Type: Integer +- Required: True + +Gives the `offset` parameter used for the query. + +> See [3.2.1.1.1. `offset`](#32111-offset) section. + +###### 3.2.1.2.3. `limit` + +- Type: Integer +- Required: True + +Gives the `limit` parameter used for the query. + +> See [3.2.1.1.2. `limit`](#32112-limit) section. + +###### 3.2.1.2.3. `total` + +- Type: Integer +- Required: True -Returns an array made of multiple index API resource objects. See [3.1.2.1. Response Definition](#3121-response-definition) section. +Gives the total number of indexes that can be browsed. #### 3.2.2. `GET` - `indexes/:index_uid` @@ -218,4 +280,5 @@ N/A ## 5. Future Possibilities - Delete `uid` or `name`. -- Rework the `primaryKey` concept \ No newline at end of file +- Rework the `primaryKey` concept +- Paginate `GET` - `/indexes` \ No newline at end of file