<commit_before># Kuzzle API Specifications

## Message structure

Messages (ie. requests sent to Kuzzle to publish data, subscribe to something, or search for specific data) use internally the following JSON structure :

```json
{
  "controller": <controller>,
  ["requestId": <requestId>,]
  "collection": <collection>,
  "action": <action>,
  [<optionnal msg attributes>]
}
```
# Kuzzle Specifications
   
## Message structure

Messages (ie. requests sent to Kuzzle to publish data, subscribe to something, or search for specific data) use internally the following JSON structure :

```json
{
 "controller": <controller>,
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <action>,
 [<optionnal msg attributes>]
}
```
* &lt;controller&gt; : **write** | **read** | **admin** | **bulk** | **subscribe**
* &lt;requestId&gt; _(optionnal)_ : a unique identifier for the message (if not set, will be automatically calculated by Kuzzle)
* &lt;collection&gt; : the collection name
* &lt;action&gt; : the action name, depending to the controller (see below)
* &lt;optionnal msg attributes&gt; : addionnal attributes, depending on the controller/action (see below), or custom attributes for your app.


### Controllers


#### write

##### Description

Create/Update/delete a document

##### Input message

```json
{
 "controller": "write",
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <"create"|"update"|"delete"|"deleteByQuery">,
 ["persist": <true|false>,]
 ["id": <id>,]
 ["body": <document>,]
}
```
* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where where the feedback messages will be sent.
* &lt;action&gt; : **create** | **update** | **delete**
* &lt;persist&gt; (only for **create** ? ):
   * if _true_: the document has to be stored to the persistent layer
   * if _false_: the document will be volatile and used only by the real-time layer
* &lt;id&gt; : the document ID :
   * for **create** : optionnal.
       will be automatically generated by Kuzzle if not set
    * for **update**: mandatory.
    * for **delete**: mandatory.
* &lt;body&gt;
   * for **create**: the document to be added to the collection.
   * for **update**: only the JSON attributes that need to be changed.
   * for **delete**: _unused_
   * for **deleteByQuery**: the query to execute for delete documents

##### Output message

_(To be defined)_

#### subscribe

##### Description

Create a filtered room and give the client the roomId.
The client SHOULD then subscribe to this room to get messages.

##### Input message

```json
{
 "controller": "subscribe",
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <"on"|"off">,
 "body": <filters>
}
```

* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where where the feedback messages will be sent.
* &lt;collection&gt; : the collection name
* &lt;action&gt; : **on** | **off**
* &lt;body&gt; the filters to subscribe/unsubscribe to (see [filters syntax] for details)

##### Output message

The room Id.

#### read

##### Description

Get a document from Kuzzle

##### Input message

```json
{
 "controller": "read",
 "requestId": <requestId>,
 "collection": <collection>,
 "action": <"get"|"search">,
 ["id": <id>,]
 ["body": <body>,]
}
```

* &lt;requestId&gt; : the local room where Kuzzle should send requested data
* &lt;collection&gt; : the collection name
* &lt;action&gt; : **get** | **search**
* &lt;id&gt; :
   * for **get** : identifies the document to retrive (if not set, the whole collection will be given)
   * for **search** : _unused_
* &lt;body&gt;
   * for **get** : _unused_
   * for **search** : the search filters (see [filters syntax] for details)

##### Output message

The document (to be defined)

#### admin

##### Description

Perform action on collection, indices, mapping...

##### Input message

```json
{
 "controller": "admin",
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <"deleteCollection"|"putMapping"|"getMapping">,
}
```
* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where the feedback messages will be sent.
* &lt;action&gt; : **deleteCollection** | **putMapping** | **getMapping**
* &lt;collection&gt; : the collection name

##### Output message

_(to be defined)_

#### bulk

##### Description

Perform many index/delete operations in a single API call.

##### Input message

```json
{
 "controller": "bulk",
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <"import">
 ["body": <body>,]
}
```
* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where where the feedback messages will be sent.
* &lt;action&gt; : **import**
* &lt;collection&gt; : default document collection for items which don’t provide one
* &lt;body&gt; : array with all actions and documents ([See doc](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference-1-3.html#api-bulk-1-3))

##### Output message

_(To be defined)_

### Protocol dependant encapsulation

As Kuzzke API can be called through distinct network protocols, the encapsulation of messages will depend  of used protocol :

#### REST

| HTTP Method | URL format | body | controller | action | comment |
| --- | --- | --- | --- | --- | --- |
| **GET** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt; | _empty_ | **read** | **get** | get a single content |
| **POST** | http(s)://kuzzle.domain/&lt;collection&gt;/_search | [`{<search_filters>}`](#search_filters) | **read** |  **search** | search document according to given filters |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt;/_create | [`{<data_content>}`](#data_content) | **write** | **create** | create the document with the given id |
| **POST** | http(s)://kuzzle.domain/&lt;collection&gt; |  [`{<data_content>}`](#data_content) | **write** | **create** | create a new document |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt; | [`{<data_content>}`](#data_content) | **write** | **update** | update the document with the given id |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt;/_update | [`{<data_content>}`](#data_content) | **write** | **update** | update the document with the given id |
| **DELETE** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt; | _empty_ | **write** | **delete** | delete the given content |
| **DELETE** | http(s)://kuzzle.domain/&lt;collection&gt;/_query | [`{<search_filters>}`](#search_filters) | **write** | **deleteByQuery** | delete documents according to given filters |
| **POST** | http(s)://kuzzle.domain/_bulk | [`{<bulk_data_content>}`](#bulk_data_content) | **bulk** |  **import** | Perform many create/update/delete operations in a single call (see [Elasticsearch bulk format](https://www.elastic.co/guide/en/elasticsearch/reference/1.x/docs-bulk.html)|
| **POST** | http(s)://kuzzle.domain/&lt;collection&gt;/_bulk | [`{<bulk_data_content>}`](#bulk_data_content) | **bulk** |  **import** | Perform many create/update/delete operations in a single call with the default given collection |
| **DELETE** | http(s)://kuzzle.domain/&lt;collection&gt; | _empty_ | **admin** | **deleteCollection** | delete the entire collection and schema |
| **GET** | http(s)://kuzzle.domain/&lt;collection&gt;/_mapping | _empty_ | **admin** | **getMapping** | Retrieve mapping definition of type. |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/_mapping | [`{<mapping_content>}`](#mapping_content) | **admin** | **putMapping** | Register specific mapping definition for a specific type |

* <a name="data_content"/>`{<data_content>}` :

   ```
   {
     "persist": <true|false|undefined>,
     "body": {
       "firstName": "Grace",
       "lastName": "Hooper"
     }
   }
   ```
   Or directly your document:
   
   ```
   {
       "firstName": "Grace",
       "lastName": "Hooper"
   }
   ```

* <a name="bulk_data_content"/>`{<bulk_data_content>}` : see [Elasticsearch bulk format](https://www.elastic.co/guide/en/elasticsearch/reference/1.x/docs-bulk.html)

* <a name="search_filters"/>`{<search_filters>}` : see [Elasticsearch query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/1.x/query-dsl.html)

* <a name="mapping_content"/>`{<mapping_content>}` : 
* 
   ```
   {
       "properties" : {
           "firstName" : {"type" : "string", "store" : true, "index" : "not_analyzed" }
       }
   }
   ```
   Or with additionnal parameters:
   
   ```
   {
       "body": {
           "ignoreConflicts": true,
           "properties" : {
               "firstName" : {"type" : "string", "store" : true, "index" : "not_analyzed" }
           }
       }
   }
   ```
   
   [See Elasticsearch format](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference-1-3.html#api-indices-putmapping-1-3)

##### Notes :

* **subscribe** controller is not available for REST API.
* requestId is not needed here. For kuzzle internal needs, its value is automatically calculated with a hash of request content.
* For each methods, we follow the [HTTP Standard Status Codes][ietf-http-status-codes] within the HTTP responses.

#### Websocket

At kuzzle side, a websocket room is listenning for each controller.

At client side, we should just encapsulate the messages like this :

```javascript
socket.emit('<controller>', {
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <action>,
 [<optionnal msg attributes>]
});
```

For each controller, kuzzle will also send a feedback to the client's socket

#### AMQP / STOMP / MQTT

Kuzzle is listening for **amq.topic** echange, filtering following routing key `<controller>.<collection>.<action>`.

Messages send to this exchange must be in JSON and contains controller/action depending attributes (see above).

Additionnaly, the client SHOULD give a queue or a connection identifier if he needs to get feedback for the request (mandatory for **subscribe** controller) :

* **AMQP** : add a `reply-to` property to the message
* **STOMP** : add a `reply-to` header, like this :

```
SEND
destination:/exchange/amq.topic/write.information.create
reply-to:/temp-queue/availabilitiy
content-type:application/json

{...}

^@
```

_(NB: This will automatically subscribe the client to the reply-to queue.)_

* **MQTT** : the client SHOULD add its client ID to the message body :

```json
{
 "mqttClientId": "lens_ZyvmGJEKRMHZzM<KEY>",
 ["requestId": <requestId>,]
 [<optionnal msg attributes>]
}
```

_(NB: Kuzzle will send messages to the topic exchange **amqp.topic**, with following destination : `mqtt/<mqttClientId>`, so the client SHOULD also subscribe to this routing key as well.)_


[//]: # (=========================================================)
[//]: # (Links)

[ietf-http-status-codes]: http://www.ietf.org/assignments/http-status-codes/http-status-codes.xml
[filters syntax]: filters.md
   

* &lt;controller&gt; : **write** | **read** | **admin** | **bulk** | **subscribe**
* &lt;requestId&gt; _(optionnal)_ : a unique identifier for the message (if not set, will be automatically calculated by Kuzzle)
* &lt;collection&gt; : the collection name
* &lt;action&gt; : the action name, depending to the controller (see below)
* &lt;optionnal msg attributes&gt; : addionnal attributes, depending on the controller/action (see below), or custom attributes for your app.


### Controllers


#### write

##### Description

Create/Update/delete a document

##### Input message

```json
{
  "controller": "write",
  ["requestId": <requestId>,]
  "collection": <collection>,
  "action": <"create"|"update"|"delete"|"deleteByQuery">,
  ["persist": <true|false>,]
  ["id": <id>,]
  ["body": <document>,]
}
```
* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where where the feedback messages will be sent.
* &lt;action&gt; : **create** | **update** | **delete**
* &lt;persist&gt; (only for **create** ? ):
    * if _true_: the document has to be stored to the persistent layer
    * if _false_: the document will be volatile and used only by the real-time layer
* &lt;id&gt; : the document ID :
    * for **create** : optionnal.
        will be automatically generated by Kuzzle if not set
     * for **update**: mandatory.
     * for **delete**: mandatory.
* &lt;body&gt;
    * for **create**: the document to be added to the collection.
    * for **update**: only the JSON attributes that need to be changed.
    * for **delete**: _unused_
    * for **deleteByQuery**: the query to execute for delete documents

##### Output message

_(To be defined)_

#### subscribe

##### Description

Create a filtered room and give the client the roomId.
The client SHOULD then subscribe to this room to get messages.

##### Input message

```json
{
  "controller": "subscribe",
  ["requestId": <requestId>,]
  "collection": <collection>,
  "action": <"on"|"off">,
  "body": <filters>
}
```

* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where where the feedback messages will be sent.
* &lt;collection&gt; : the collection name
* &lt;action&gt; : **on** | **off**
* &lt;body&gt; the filters to subscribe/unsubscribe to (see [filters syntax] for details)

##### Output message

The room Id.

#### read

##### Description

Get a document from Kuzzle

##### Input message

```json
{
  "controller": "read",
  "requestId": <requestId>,
  "collection": <collection>,
  "action": <"get"|"search">,
  ["id": <id>,]
  ["body": <filters>,]
}
```

* &lt;requestId&gt; : the local room where Kuzzle should send requested data
* &lt;collection&gt; : the collection name
* &lt;action&gt; : **get** | **search**
* &lt;id&gt; :
    * for **get** : identifies the document to retrive (if not set, the whole collection will be given)
    * for **search** : _unused_
* &lt;body&gt;
    * for **get** : _unused_
    * for **search** : the search filters (see [filters syntax] for details)

##### Output message

The document (to be defined)

#### admin

##### Description

Delete a mapping and entire collection

##### Input message

```json
{
  "controller": "admin",
  ["requestId": <requestId>,]
  "collection": <collection>,
  "action": <"deleteCollection">,
}
```
* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where where the feedback messages will be sent.
* &lt;action&gt; : **deleteCollection**
* &lt;collection&gt; : the collection name

##### Output message

_(to be defined)_

#### bulk

##### Description

Perform many index/delete operations in a single API call.

##### Input message

```json
{
  "controller": "bulk",
  ["requestId": <requestId>,]
  "collection": <collection>,
  "action": <"import">
  ["body": <actions>,]
}
```
* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where where the feedback messages will be sent.
* &lt;action&gt; : **import**
* &lt;collection&gt; : default document collection for items which don’t provide one
* &lt;body&gt; : array with all actions and documents ([See doc](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference-1-3.html#api-bulk-1-3))

##### Output message

_(To be defined)_

### Protocol dependant encapsulation

As Kuzzke API can be called through distinct network protocols, the encapsulation of messages will depend  of used protocol :

#### REST

| HTTP Method | URL format | body | controller | action | comment |
| --- | --- | --- | --- | --- | --- |
| **GET** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt; | _empty_ | **read** | **get** | get a single content |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt; | `{<data_content>}` | **write** | **update** | update the document with the given id |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt;/_update | `{<data_content>}` | **write** | **update** | update the document with the given id |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt;/_create | `{<data_content>}` | **write** | **create** | create the document with the given id |
| **POST** | http(s)://kuzzle.domain/&lt;collection&gt; |  `{<data_content>}` | **write** | **create** | create a new document |
| **POST** | http(s)://kuzzle.domain/&lt;collection&gt;/_search | `{<search_filters>}` | **read** |  **search** | search document according to given filters |
| **POST** | http(s)://kuzzle.domain/_bulk | `{<bulk_data_content>}` | **bulk** |  **import** | Perform many create/update/delete operations in a single call (see [ElasticSearch bulk format](https://www.elastic.co/guide/en/elasticsearch/reference/1.x/docs-bulk.html)|
| **POST** | http(s)://kuzzle.domain/&lt;collection&gt;/_bulk | `{<bulk_data_content>}` | **bulk** |  **import** | Perform many create/update/delete operations in a single call with the default given collection |
| **DELETE** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt; | _empty_ | **write** | **delete** | delete the given content |
| **DELETE** | http(s)://kuzzle.domain/&lt;collection&gt;/_query | `{<search_filters>}` | **write** | **deleteByQuery** | delete documents according to given filters |
| **DELETE** | http(s)://kuzzle.domain/&lt;collection&gt; | _empty_ | **admin** | **deleteCollection** | delete the entire collection and schema |

* `{<data_content>}` :

    ```
    {
      "persist": <true|false|undefined>,
      "body": {
        "firstName": "Grace",
        "lastName": "Hooper"
      }
    }
    ```
    Or directly your document:
    ```
    {
        "firstName": "Grace",
        "lastName": "Hooper"
    }
    ```

* `{<bulk_data_content>}` : see [Elasticsearch bulk format](https://www.elastic.co/guide/en/elasticsearch/reference/1.x/docs-bulk.html)

* `{<search_filters>}` : see [Elasticsearch query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/1.x/query-dsl.html)


##### Notes :

* **subscribe** controller is not available for REST API.
* requestId is not needed here. For kuzzle internal needs, its value is automatically calculated with a hash of request content.
* For each methods, we follow the [HTTP Standard Status Codes][ietf-http-status-codes] within the HTTP responses.

#### Websocket

At kuzzle side, a websocket room is listenning for each controller.

At client side, we should just encapsulate the messages like this :

```javascript
socket.emit('<controller>', {
  ["requestId": <requestId>,]
  "collection": <collection>,
  "action": <action>,
  [<optionnal msg attributes>]
});
```

For each controller, kuzzle will also send a feedback to the client's socket

#### AMQP / STOMP / MQTT

Kuzzle is listening for **amq.topic** echange, filtering following routing key `<controller>.<collection>.<action>`.

Messages send to this exchange must be in JSON and contains controller/action depending attributes (see above).

Additionnaly, the client SHOULD give a queue or a connection identifier if he needs to get feedback for the request (mandatory for **subscribe** controller) :

* **AMQP** : add a `reply-to` property to the message
* **STOMP** : add a `reply-to` header, like this :

```
SEND
destination:/exchange/amq.topic/write.information.create
reply-to:/temp-queue/availabilitiy
content-type:application/json

{...}

^@
```

_(NB: This will automatically subscribe the client to the reply-to queue.)_

* **MQTT** : the client SHOULD add its client ID to the message body :

```json
{
  "mqttClientId": "lens_ZyvmGJEKRMHZzMZQfX151szh8zC",
  ["requestId": <requestId>,]
  [<optionnal msg attributes>]
}
```

_(NB: Kuzzle will send messages to the topic exchange **amqp.topic**, with following destination : `mqtt/<mqttClientId>`, so the client SHOULD also subscribe to this routing key as well.)_


[//]: # (=========================================================)
[//]: # (Links)

[ietf-http-status-codes]: http://www.ietf.org/assignments/http-status-codes/http-status-codes.xml
[filters syntax]: filters.md
<commit_msg>fix merge and nitpick in doc<commit_after># Kuzzle API Specifications

## Message structure

Messages (ie. requests sent to Kuzzle to publish data, subscribe to something, or search for specific data) use internally the following JSON structure :

```json
{
 "controller": <controller>,
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <action>,
 [<optionnal msg attributes>]
}
```
* &lt;controller&gt; : **write** | **read** | **admin** | **bulk** | **subscribe**
* &lt;requestId&gt; _(optionnal)_ : a unique identifier for the message (if not set, will be automatically calculated by Kuzzle)
* &lt;collection&gt; : the collection name
* &lt;action&gt; : the action name, depending to the controller (see below)
* &lt;optionnal msg attributes&gt; : addionnal attributes, depending on the controller/action (see below), or custom attributes for your app.


### Controllers


#### write

##### Description

Create/Update/delete a document

##### Input message

```json
{
 "controller": "write",
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <"create"|"update"|"delete"|"deleteByQuery">,
 ["persist": <true|false>,]
 ["id": <id>,]
 ["body": <body>,]
}
```
* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where where the feedback messages will be sent.
* &lt;action&gt; : **create** | **update** | **delete**
* &lt;persist&gt; (only for **create** ? ):
   * if _true_: the document has to be stored to the persistent layer
   * if _false_: the document will be volatile and used only by the real-time layer
* &lt;id&gt; : the document ID :
   * for **create** : optionnal.
       will be automatically generated by Kuzzle if not set
    * for **update**: mandatory.
    * for **delete**: mandatory.
* &lt;body&gt;
   * for **create**: the document to be added to the collection.
   * for **update**: only the JSON attributes that need to be changed.
   * for **delete**: _unused_
   * for **deleteByQuery**: the query to execute for delete documents

##### Output message

_(To be defined)_

#### subscribe

##### Description

Create a filtered room and give the client the roomId.
The client SHOULD then subscribe to this room to get messages.

##### Input message

```json
{
 "controller": "subscribe",
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <"on"|"off">,
 "body": <body>
}
```

* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where where the feedback messages will be sent.
* &lt;collection&gt; : the collection name
* &lt;action&gt; : **on** | **off**
* &lt;body&gt; the filters to subscribe/unsubscribe to (see [filters syntax] for details)

##### Output message

The room Id.

#### read

##### Description

Get a document from Kuzzle

##### Input message

```json
{
 "controller": "read",
 "requestId": <requestId>,
 "collection": <collection>,
 "action": <"get"|"search">,
 ["id": <id>,]
 ["body": <body>,]
}
```

* &lt;requestId&gt; : the local room where Kuzzle should send requested data
* &lt;collection&gt; : the collection name
* &lt;action&gt; : **get** | **search**
* &lt;id&gt; :
   * for **get** : identifies the document to retrive (if not set, the whole collection will be given)
   * for **search** : _unused_
* &lt;body&gt;
   * for **get** : _unused_
   * for **search** : the search filters (see [filters syntax] for details)

##### Output message

The document (to be defined)

#### admin

##### Description

Perform action on collection, indices, mapping...

##### Input message

```json
{
 "controller": "admin",
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <"deleteCollection"|"putMapping"|"getMapping">,
}
```

* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where the feedback messages will be sent.
* &lt;action&gt; : **deleteCollection** | **putMapping** | **getMapping**
* &lt;collection&gt; : the collection name

##### Output message

_(to be defined)_

#### bulk

##### Description

Perform many index/delete operations in a single API call.

##### Input message

```json
{
 "controller": "bulk",
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <"import">
 ["body": <body>,]
}
```
* &lt;requestId&gt; _(optionnal)_ : if set : identifies the room where where the feedback messages will be sent.
* &lt;action&gt; : **import**
* &lt;collection&gt; : default document collection for items which don’t provide one
* &lt;body&gt; : array with all actions and documents ([See doc](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference-1-3.html#api-bulk-1-3))

##### Output message

_(To be defined)_

### Protocol dependant encapsulation

As Kuzzke API can be called through distinct network protocols, the encapsulation of messages will depend  of used protocol :

#### REST

| HTTP Method | URL format | body | controller | action | comment |
| --- | --- | --- | --- | --- | --- |
| **GET** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt; | _empty_ | **read** | **get** | get a single content |
| **POST** | http(s)://kuzzle.domain/&lt;collection&gt;/_search | [`{<search_filters>}`](#search_filters) | **read** |  **search** | search document according to given filters |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt;/_create | [`{<data_content>}`](#data_content) | **write** | **create** | create the document with the given id |
| **POST** | http(s)://kuzzle.domain/&lt;collection&gt; |  [`{<data_content>}`](#data_content) | **write** | **create** | create a new document |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt; | [`{<data_content>}`](#data_content) | **write** | **update** | update the document with the given id |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt;/_update | [`{<data_content>}`](#data_content) | **write** | **update** | update the document with the given id |
| **DELETE** | http(s)://kuzzle.domain/&lt;collection&gt;/&lt;id&gt; | _empty_ | **write** | **delete** | delete the given content |
| **DELETE** | http(s)://kuzzle.domain/&lt;collection&gt;/_query | [`{<search_filters>}`](#search_filters) | **write** | **deleteByQuery** | delete documents according to given filters |
| **POST** | http(s)://kuzzle.domain/_bulk | [`{<bulk_data_content>}`](#bulk_data_content) | **bulk** |  **import** | Perform many create/update/delete operations in a single call (see [Elasticsearch bulk format](https://www.elastic.co/guide/en/elasticsearch/reference/1.x/docs-bulk.html)|
| **POST** | http(s)://kuzzle.domain/&lt;collection&gt;/_bulk | [`{<bulk_data_content>}`](#bulk_data_content) | **bulk** |  **import** | Perform many create/update/delete operations in a single call with the default given collection |
| **DELETE** | http(s)://kuzzle.domain/&lt;collection&gt; | _empty_ | **admin** | **deleteCollection** | delete the entire collection and schema |
| **GET** | http(s)://kuzzle.domain/&lt;collection&gt;/_mapping | _empty_ | **admin** | **getMapping** | Retrieve mapping definition of type. |
| **PUT** | http(s)://kuzzle.domain/&lt;collection&gt;/_mapping | [`{<mapping_content>}`](#mapping_content) | **admin** | **putMapping** | Register specific mapping definition for a specific type |

* <a name="data_content"/>`{<data_content>}` :

   ```
   {
     "persist": <true|false|undefined>,
     "body": {
       "firstName": "Grace",
       "lastName": "Hooper"
     }
   }
   ```

   Or directly your document:
   
   ```
   {
       "firstName": "Grace",
       "lastName": "Hooper"
   }
   ```

* <a name="bulk_data_content"/>`{<bulk_data_content>}` : see [Elasticsearch bulk format](https://www.elastic.co/guide/en/elasticsearch/reference/1.x/docs-bulk.html)

* <a name="search_filters"/>`{<search_filters>}` : see [Elasticsearch query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/1.x/query-dsl.html)

* <a name="mapping_content"/>`{<mapping_content>}` : 
* 
   ```
   {
       "properties" : {
           "firstName" : {"type" : "string", "store" : true, "index" : "not_analyzed" }
       }
   }
   ```
   Or with additionnal parameters:
   
   ```
   {
       "body": {
           "ignoreConflicts": true,
           "properties" : {
               "firstName" : {"type" : "string", "store" : true, "index" : "not_analyzed" }
           }
       }
   }
   ```
   
   [See Elasticsearch format](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference-1-3.html#api-indices-putmapping-1-3)

##### Notes :

* **subscribe** controller is not available for REST API.
* requestId is not needed here. For kuzzle internal needs, its value is automatically calculated with a hash of request content.
* For each methods, we follow the [HTTP Standard Status Codes][ietf-http-status-codes] within the HTTP responses.

#### Websocket

At kuzzle side, a websocket room is listenning for each controller.

At client side, we should just encapsulate the messages like this :

```javascript
socket.emit('<controller>', {
 ["requestId": <requestId>,]
 "collection": <collection>,
 "action": <action>,
 [<optionnal msg attributes>]
});
```

For each controller, kuzzle will also send a feedback to the client's socket

#### AMQP / STOMP / MQTT

Kuzzle is listening for **amq.topic** echange, filtering following routing key `<controller>.<collection>.<action>`.

Messages send to this exchange must be in JSON and contains controller/action depending attributes (see above).

Additionnaly, the client SHOULD give a queue or a connection identifier if he needs to get feedback for the request (mandatory for **subscribe** controller) :

* **AMQP** : add a `reply-to` property to the message
* **STOMP** : add a `reply-to` header, like this :

```
SEND
destination:/exchange/amq.topic/write.information.create
reply-to:/temp-queue/availabilitiy
content-type:application/json

{...}

^@
```

_(NB: This will automatically subscribe the client to the reply-to queue.)_

* **MQTT** : the client SHOULD add its client ID to the message body :

```json
{
 "mqttClientId": "lens_ZyvmGJEKRMHZzMZQfX151szh8zC",
 ["requestId": <requestId>,]
 [<optionnal msg attributes>]
}
```

_(NB: Kuzzle will send messages to the topic exchange **amqp.topic**, with following destination : `mqtt/<mqttClientId>`, so the client SHOULD also subscribe to this routing key as well.)_


[ietf-http-status-codes]: http://www.ietf.org/assignments/http-status-codes/http-status-codes.xml
[filters syntax]: filters.md
{'fraction_non_alphanumeric': 0.18086089654717105, 'fraction_numerical': 0.0012213639664620057, 'mean_word_length': 4.514197306152166, 'pattern_counts': {'":': 130, '<': 166, '<?xml version=': 0, '>': 166, 'https://': 14, 'lorem ipsum': 0, 'www.': 17, 'xml': 3}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6118408', 'n_tokens_mistral': 9773, 'n_tokens_neox': 9432, 'n_words': 2830}