diff --git a/text/0132-indexes-api.md b/text/0132-indexes-api.md new file mode 100644 index 00000000..3420554f --- /dev/null +++ b/text/0132-indexes-api.md @@ -0,0 +1,221 @@ +# Indexes API + +## 1. Summary + +This specification describes the indexes API endpoints. The endpoint gives the possibility to get, get all, create, update and delete Meilsearch indexes. + +## 2. Motivation +N/A + +## 3. Functional Specification + +Indexes contain a set of documents in which to search and have their specific settings. + +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 + +| Field | Type | Required | +|-------------------------------|-----------------|----------| +| [uid](#311-uid) | string | True | +| [name](#312-name) | string | False | +| [primaryKey](#313-primaryKey) | string / `null` | False | +| [createdAt](#314-createdAt) | string | False | +| [updatedAt](#315-updatedAt) | string | False | + +#### 3.1.1. `uid` + +- Type: string +- Required: true + +A unique identifier for the index. + +This field is mandatory when creating an index and cannot be changed afterwards. + +The field `uid` can be an integer or a string containing only alphanumeric characters, hyphens (-) and underscores (_). + +#### 3.1.2. `name` + +- Type: string +- Required: false + +This field is automatically generated by the engine when creating an index and is equal to the value of `uid`. + +It is not possible to give a custom value to `name` when creating or updating an index. + +#### 3.1.3. `primaryKey` + +- Type: string +- Required: false +- Default: `null` + +The primary key is the attribute in a document whose value is unique amongst all the other documents. + +This field allows bypassing the auto-inference mechanism of the document identifiers. + +By default, the `primaryKey` will be chosen by the auto-inference mechanism by the engine when a first document is indexed. + +Specifying this field tells the engine to use the document attribute specified in `primaryKey` and bypasses this mechanism. + +When the index is empty, it is possible to modify the `primaryKey`. + +#### 3.1.4. `createdAt` + +- Type: string +- Required: false + +The creation date on which the index has been created. + +Automatically generated by the engine at the creation of an index. + +Represented with the `RFC 3339` format. + +#### 3.1.5. `updatedAt` + +- Type: string +- Required: false + +The latest date on which the index has been updated. + +Automatically generated by the engine at the creation/update of an index. + +Represented wih the `RFC 3339` format. + +### 3.2. API Endpoints Definition + +Manipulate indexes of a Meilisearch instance. + +- [3.2.1. `GET` - `indexes`](#321-get---indexes) +- [3.2.2. `GET` - `indexes/:index_uid`](#322-get---indexesindexuid) +- [3.2.3. `POST` - `indexes`](#323-post---indexes) +- [3.2.4. `PUT` - `indexes/:index_uid`](#324-put---indexesindexuid) +- [3.2.5. `DELETE` - `indexes/:index_uid`](#325-delete---indexesindexuid) + +#### 3.2.1. `GET` - `indexes` + +List all indexes of a Meilisearch instance. + +##### 3.2.1.1. Response Definition + +Returns an array made of multiple index API resource objects. See [3.1.2.1. Response Definition](#3121-response-definition) section. + +#### 3.2.2. `GET` - `indexes/:index_uid` + +Fetch an index of a Meilisearch instance. + +##### 3.2.2.1. Response Definition + +| Field | Type | Required | +|--------------------------|--------------------------|----------| +| `uid` | string | true | +| `name` | string | true | +| `primaryKey` | string / `null` | true | +| `createdAt` | string | true | +| `updatedAt` | string | true | + +The `name` field has the same value as the `uid`. + +##### 3.2.2.2. Errors + +- 🔴 If the requested `index_uid` does not exist, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error. + +#### 3.2.3. `POST` - `indexes` + +Creates an index. + +##### 3.2.3.1. Request Payload Definition + +| Field | Type | Required | +|--------------------------|--------------------------|----------| +| `uid` | string | true | +| `primaryKey` | string / `null` | false | + +##### 3.2.3.2. Response Definition + +When the request is successful, Meilisearch returns the HTTP code `202 Accepted`. The response's content is the summarized representation of the received asynchronous task. + +See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-task-object-for-202-accepted). + +##### 3.2.3.3. Errors + +- 🔴 Omitting Content-Type header returns a [missing_content_type](0061-error-format-and-definitions.md#missing_content_type) error. +- 🔴 Sending an empty Content-Type returns an [invalid_content_type](0061-error-format-and-definitions.md#invalid_content_type) error. +- 🔴 Sending a different Content-Type than `application/json` returns an [invalid_content_type](0061-error-format-and-definitions.md#invalid_content_type) error. +- 🔴 Sending an empty payload returns a [missing_payload](0061-error-format-and-definitions.md#missing_payload) error. +- 🔴 Sending an invalid JSON payload returns a [malformed_payload](0061-error-format-and-definitions.md#malformed_payload) error. +- 🔴 Sending a value with a different type than `string` for `uid` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending an invalid `uid` returns an [invalid_index_uid](0061-error-format-and-definitions.md#invalid_index_uid) error. +- 🔴 Sending a value with a different type than `string` or `null` for `primaryKey` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. + +###### 3.2.3.3.1. Async Errors + +- 🔴 When Meilisearch is secured by a master key, if the API Key used do not have the `indexes.create` action defined, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error in the related asynchronous `task` resource. See [3.2.2.2. Response Definition](#3222-response-definition). +- 🔴 Sending a `uid` that already exists returns an [index_already_exists](0061-error-format-and-definitions.md#index_already_exists) error. + +#### 3.2.4. `PUT` - `indexes/:index_uid` + +Updates an index. + +The `primaryKey` field can be updated when the index is empty. If the `primaryKey` is not defined, the indexing process will try to auto-infer the `primaryKey` by searching the first attribute containing `id` in the first document payload to index. + +##### 3.2.4.1. Request Payload Definition + +| Field | Type | Required | +|--------------------------|--------------------------|----------| +| `primaryKey` | string / `null` | False | + +##### 3.2.4.2. Response Definition + +When the request is successful, Meilisearch returns the HTTP code `202 Accepted`. The response's content is the summarized representation of the received asynchronous task. + +See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-task-object-for-202-accepted). + +##### 3.2.4.3. Errors + +- 🔴 Omitting Content-Type header returns a [missing_content_type](0061-error-format-and-definitions.md#missing_content_type) error. +- 🔴 Sending an empty Content-Type returns an [invalid_content_type](0061-error-format-and-definitions.md#invalid_content_type) error. +- 🔴 Sending a different Content-Type than `application/json` returns an [invalid_content_type](0061-error-format-and-definitions.md#invalid_content_type) error. +- 🔴 Sending an empty payload returns a [missing_payload](0061-error-format-and-definitions.md#missing_payload) error. +- 🔴 Sending an invalid JSON payload returns a [malformed_payload](0061-error-format-and-definitions.md#malformed_payload) error. + +###### 3.2.4.3.1. Async Errors + +- 🔴 When updating the `primaryKey`, if the previous `primaryKey` value has already been used for a document, the API returns an [index_primary_key_already_exists](0061-error-format-and-definitions.md#index_primary_key_already_exists) error. +- 🔴 If the requested `index_uid` does not exist, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error. + +#### 3.2.5. `DELETE` - `indexes/:index_uid` + +Deletes an index. + +##### 3.2.4.1. Response Definition + +When the request is successful, Meilisearch returns the HTTP code `202 Accepted`. The response's content is the summarized representation of the received asynchronous task. + +See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-task-object-for-202-accepted). + +##### 3.2.4.2. Errors + +###### 3.2.4.2.1 Async Errors + +- 🔴 If the requested `index_uid` does not exist, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error. + +#### 3.2.6. General Errors + +These errors apply to all endpoints described here. + +##### 3.2.6.1 Auth Errors + +The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). + +- 🔴 Accessing this route without the `Authorization` header returns a [missing_authorization_header](0061-error-format-and-definitions.md#missing_authorization_header) error. +- 🔴 Accessing this route with a key that does not have the required permissions (i.e. other than the master-key) returns an [invalid_api_key](0061-error-format-and-definitions.md#invalid_api_key) error. + +## 4. Technical Details +N/A + +## 5. Future Possibilities +- Delete `uid` or `name`. +- Rework the `primaryKey` concept \ No newline at end of file