API Guideline - Return list of API resources under a `results` array #138

gmourier · 2022-03-31T12:07:09Z

Why?

In order to stabilize the APIs around a convention, we add resources under a results array when they can be listed.

This is already the case for the tasks and API Keys resources which have made this change along the way.

The /search endpoints are not affected by these changes but this can be reconsidered with caution. hits seem to be effective and changing it would cause a big breaking change. hits is already well established in the market e.g. elasticsearch, algolia, typesense.

The stats API is not concerned for the moment and maybe concerned later given feedback and what it could become. The idea behind it is that this resource does not only return index statistics but also more global statistics which makes the use of results less straightforward.

TODO

Changes

Returns index API resources on GET - /indexes under a results array + offset/limit pagination.
- Add limit (Default: 20) and offset(Default: 0) query parameters.
- Add limit, offset and total in the response body.
Returns document API resources on /documents under a results array.
- Add limit, offset and total in the response body.
Add an offset/limit pagination on GET - /keys
- Add limit (Default: 20) and offset(Default: 0) query parameters.
- Add limit, offset and total in the response body.

github-actions · 2022-04-06T10:36:02Z

🚨 Breaking API change detected:

Modified (3)

GET /indexes
- Query parameters added: limit, offset
- [Breaking] Response modified: 200
  - [Breaking] Body attributes added: results, limit, offset, total
  - [Breaking] Body attributes removed: uid, name, primaryKey, createdAt, updatedAt, Additional properties are NOT allowed
GET /indexes/{indexUid}/documents
- [Breaking] Response modified: 200
  - [Breaking] Body attributes added: results, limit, offset, total
  - [Breaking] Body attribute removed: Additional properties are allowed
GET /keys
- Query parameters added: limit, offset
- Response modified: 200
  - Body attributes added: limit, offset, total
  - [Breaking] Body attribute modified: results

View documentation diff

Powered by Bump

text/0124-documents-api.md

text/0132-indexes-api.md

brunoocasali

Awesome spec @gmourier :)

The /search endpoints are not affected by these changes but this can be reconsidered with caution. hits seem to be effective and changing it would cause a big breaking change.

I really like standards, but in this case, it does not seem so appropriate to change from hits to results, because this word is already well established in the market, elasticsearch, algolia, typesense.

gmourier · 2022-04-12T16:40:50Z

Thanks, @brunoocasali. Absolutely, this is also a very good reason!

text/0085-api-keys.md

text/0124-documents-api.md

bidoubiwa

I made some suggestions in wording in the indexes response, if you agree, can you apply them to all other occurrences ?

text/0132-indexes-api.md

curquiza

👌

bidoubiwa

LGTM 🔥

Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com>

…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>

* Bump open-api.yml to v0.28 * Telemetry - Add `x-meilisearch-client` query parameter (#145) * Introduce the x-meilisearch-client query parameter * Update text/0034-telemetry-policies.md Co-authored-by: Bruno Casali <brunoocasali@gmail.com> * Update text/0034-telemetry-policies.md Co-authored-by: Bruno Casali <brunoocasali@gmail.com> Co-authored-by: Bruno Casali <brunoocasali@gmail.com> * GeoSearch — Support string type for `_geo` `lat` and `lng` fields (#83) * Update specification to support string type for _geo lat and lng fields * mention types mixing for _geo object * Tasks API - Rename `uid` to `taskUid` in the `202 - Accepted` Summarized Task Response (#144) * Rename 202 uid to taskUid * Update text/0060-tasks-api.md Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com> Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com> * Tasks API - Seek/Keyset based pagination (#115) * Move cursor based pagination spec to tasks API spec * remove pagination as a future capability * Clarify boundaries for limit query parameter * Update OpenApi specification * Remove limit field boundaries * Apply suggestions from code review Co-authored-by: Clément Renault <renault.cle@gmail.com> * Update open-api.yml and removes cursor term mentions * Update text/0060-tasks-api.md Co-authored-by: Tommy <68053732+dichotommy@users.noreply.github.com> * Remove route mention in seek-keyset pagination section Co-authored-by: Clément Renault <renault.cle@gmail.com> Co-authored-by: Tommy <68053732+dichotommy@users.noreply.github.com> * Tasks API - Filter tasks list by `type`/`status`/`indexUid` (#116) * move filtering tasks by status/type parameter to task api spec * Update specification * Add details about case-sensitivy + rework error message * Introducing naming changes plus make the specification a source of truth instead of a changelog * Remove a future possibility being introduced * misc - replace createIndex to the right type and add the missing type field to the 202 Response resource * Dumps API - Make dump creation an asynchronous task (#139) * wip * Make a dump creation a visible asynchronous task * Add precisions * Update open-api.yml * Add ommited type field for summarized task response * Add future possibilities * Apply suggestions from code review Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com> * Precise that indexUid can be null * Precise priorization of dumpCreation task over other task types * Keep taskUid for 202 response * remove dumps.get API key action Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com> * Search API - Remove/Rename confusing fields (#135) * Rename nbHits, remove exhaustive* boolean fields * Rename approximativeNbHits to estimatedTotalHits * Update open-api.yaml * Apply naming changes for facet distribution and showing matches position * Add a telemetry for facet distribution usage * 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> * Remove name field (#140) * Documents API - `displayedAttributes` should not impact the documents API / Rename `attributesToRetrieve` to `fields` (#143) * Specifies that displayedAttributes setting does not impact the GET documents endpoint * Rename attributeToRetrieve to fields on /documents * Add a future possibily to rejectt a field from a document in the given response * Precise behavior details about fields query parameter * Add fields query parameter on GET /indexes/{index}/documents/{docId} * API Keys - Determinist API Keys + Security changes (#148) * Add an uid to make API Keys determinists, plus add a non-unique human readable name field to ease reading information * Describe errors for uid and name fields * Apply suggestions from code review Co-authored-by: Bruno Casali <brunoocasali@gmail.com> * misc: add precisions * Reorganize route descriptions * Update error_code when API Key already exists for a given uid * Apply suggestions from code review Co-authored-by: Many the fish <legendre.maxime.isn@gmail.com> * Add new keys actions, remove master-key changes, introduce a new error for immutable field and update tenant token * Update open-api spec * Update immutable_field error message * Apply suggestions from code review Co-authored-by: Many the fish <legendre.maxime.isn@gmail.com> * Mention that the Default Admin API Key can manage keys * Specify that the JWT Tenant Token must be enrypted with the API Key value * Update the spec regarding the description of the Admin API Key to be up-to-date * Add uid_or_key url param to update and delete a key * Update text/0085-api-keys.md Co-authored-by: Many the fish <legendre.maxime.isn@gmail.com> * Update text/0085-api-keys.md Co-authored-by: Many the fish <legendre.maxime.isn@gmail.com> Co-authored-by: Bruno Casali <brunoocasali@gmail.com> Co-authored-by: Many the fish <legendre.maxime.isn@gmail.com> Co-authored-by: Kerollmops <clement@meilisearch.com> * Geosearch - Enhance lat/lng format error messages (#149) * Update the geosearch error message * misc: organiser error message in the right specification Co-authored-by: Guillaume Mourier <guillaume@meilisearch.com> * Introduces HTTP Verbs changesto be compliant regarding a Rest API (#152) * Telemetry - Replace `x-meilisearch-client` query parameter by `X-Meilisearch-Client` header (#150) * Removes x-meilisearch-client, replace it by a header * Remove capslock * fix typo (#151) * Mention telemetry.meilisearch.com (#153) * update ranking rules error message (#154) * Misc — Update dump versions compatibility table (#156) * Update dump table * Update text/0105-dumps-api.md * Settings API - Customize the hard limits for `pagination` and `faceting` (#157) * Introduces specification files * Update files name * branch telemetry * Update open-api.yml * Update text/0034-telemetry-policies.md Co-authored-by: Clément Renault <renault.cle@gmail.com> * update open-api.yml * Update text/157-faceting-setting-api.md Co-authored-by: Clément Renault <renault.cle@gmail.com> * Rename limitedTo to maxTotalHits * Specify order of returned facet Co-authored-by: Clément Renault <renault.cle@gmail.com> * Add dumpCreation task type to OpenAPI.yml * Tasks filtering params to be in query instead of path on OpenAPI spec Co-authored-by: Bruno Casali <brunoocasali@gmail.com> Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com> Co-authored-by: Clément Renault <renault.cle@gmail.com> Co-authored-by: Tommy <68053732+dichotommy@users.noreply.github.com> Co-authored-by: Many the fish <legendre.maxime.isn@gmail.com> Co-authored-by: Kerollmops <clement@meilisearch.com> Co-authored-by: Tamo <tamo@meilisearch.com> Co-authored-by: ad hoc <postma.marin@protonmail.com> Co-authored-by: Clémentine Urquizar - curqui <clementine@meilisearch.com>

gmourier added v0.28 In Progress Feature specification is in elaboration. Important changes can still occurs in the specification. Q2:2022 labels Mar 31, 2022

gmourier mentioned this pull request Mar 31, 2022

Release v0.28.0 #137

Merged

1 task

gmourier force-pushed the manage-list-of-resources-under-results-array branch 2 times, most recently from 9d50e1a to 37cc595 Compare April 6, 2022 10:35

gmourier added Ready For Review Feature specification must be reviewed. and removed In Progress Feature specification is in elaboration. Important changes can still occurs in the specification. labels Apr 6, 2022

gmourier requested review from bidoubiwa, brunoocasali, irevoire and guimachiavelli April 6, 2022 11:45

bidoubiwa suggested changes Apr 7, 2022

View reviewed changes

text/0124-documents-api.md Show resolved Hide resolved

text/0124-documents-api.md Outdated Show resolved Hide resolved

text/0132-indexes-api.md Outdated Show resolved Hide resolved

brunoocasali previously approved these changes Apr 11, 2022

View reviewed changes

gmourier dismissed brunoocasali’s stale review via 7c8b330 April 13, 2022 14:20

guimachiavelli reviewed Apr 14, 2022

View reviewed changes

text/0085-api-keys.md Show resolved Hide resolved

text/0085-api-keys.md Show resolved Hide resolved

text/0124-documents-api.md Show resolved Hide resolved

text/0124-documents-api.md Show resolved Hide resolved

bidoubiwa reviewed Apr 14, 2022

View reviewed changes

text/0132-indexes-api.md Show resolved Hide resolved

text/0132-indexes-api.md Show resolved Hide resolved

text/0132-indexes-api.md Show resolved Hide resolved

curquiza previously approved these changes Apr 19, 2022

View reviewed changes

gmourier added Q3:2021 Q3:2022 and removed Q2:2022 Q3:2021 labels Apr 21, 2022

This was referenced May 4, 2022

Changes in Indexes resources meilisearch/meilisearch#2373

Closed

Change of the API key resource meilisearch/meilisearch#2369

Closed

gmourier dismissed curquiza’s stale review via 1f9b162 May 16, 2022 12:09

gmourier force-pushed the manage-list-of-resources-under-results-array branch 3 times, most recently from 0ae16be to b3226b3 Compare May 17, 2022 12:21

gmourier force-pushed the manage-list-of-resources-under-results-array branch 2 times, most recently from fdbeaa4 to ee1dbc4 Compare May 17, 2022 12:32

bidoubiwa previously approved these changes May 17, 2022

View reviewed changes

curquiza mentioned this pull request May 17, 2022

Changes in the Documents resources meilisearch/meilisearch#2372

Closed

6 tasks

gmourier changed the title ~~API Guide-line: Return list of API resources under a results array~~ API Guideline: Return list of API resources under a results array May 23, 2022

gmourier changed the title ~~API Guideline: Return list of API resources under a results array~~ API Guideline - Return list of API resources under a results array May 23, 2022

ManyTheFish mentioned this pull request May 30, 2022

Pagination of the /keys ressources meilisearch/meilisearch#2442

Closed

4 tasks

This was referenced Jun 7, 2022

v0.28: API key updates meilisearch/documentation#1699

Closed

v0.28: Indexes API changes meilisearch/documentation#1701

Closed

gmourier and others added 8 commits July 7, 2022 13:09

Place list of documents under a results array on /documents

fad6b2a

Add results array for indexes object list

f831bb1

Add the future of indexes pagination

4e09a60

Update open-api.yml

bb343e6

Fix typo

1a2f96f

Apply suggestions from code review

893aaed

Co-authored-by: cvermand <33010418+bidoubiwa@users.noreply.github.com>

Add offset/limit pagination for indexes and API keys

d324feb

Try to add multipe refs to a response object

b7d7e2b

gmourier dismissed bidoubiwa’s stale review via b7d7e2b July 7, 2022 11:17

gmourier force-pushed the manage-list-of-resources-under-results-array branch from ee1dbc4 to b7d7e2b Compare July 7, 2022 11:17

gmourier merged commit 1f04f5b into develop Jul 7, 2022

gmourier deleted the manage-list-of-resources-under-results-array branch July 7, 2022 11:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API Guideline - Return list of API resources under a `results` array #138

API Guideline - Return list of API resources under a `results` array #138

gmourier commented Mar 31, 2022 •

edited

Loading

github-actions bot commented Apr 6, 2022 •

edited

Loading

brunoocasali left a comment

gmourier commented Apr 12, 2022 •

edited

Loading

bidoubiwa left a comment

curquiza left a comment

bidoubiwa left a comment

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

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

Conversation

gmourier commented Mar 31, 2022 • edited Loading

Why?

TODO

Changes

github-actions bot commented Apr 6, 2022 • edited Loading

Modified (3)

brunoocasali left a comment

Choose a reason for hiding this comment

gmourier commented Apr 12, 2022 • edited Loading

bidoubiwa left a comment

Choose a reason for hiding this comment

curquiza left a comment

Choose a reason for hiding this comment

bidoubiwa left a comment

Choose a reason for hiding this comment

API Guideline - Return list of API resources under a `results` array #138

API Guideline - Return list of API resources under a `results` array #138

gmourier commented Mar 31, 2022 •

edited

Loading

github-actions bot commented Apr 6, 2022 •

edited

Loading

gmourier commented Apr 12, 2022 •

edited

Loading