Merge pull request #297 from kuzzleio/3-data-validation

Add documentation for specification routes in SDK

src/api-documentation/controller-collection/delete-specifications.md

@@ -9,7 +9,6 @@ title: deleteSpecifications
 
 # deleteSpecifications
 
-
 <blockquote class="js">
 <p>
 **URL:** `http://kuzzle:7512/<index>/<collection>/_specifications`  
@@ -42,11 +41,11 @@ title: deleteSpecifications
   "collection": "<collection>",
   "action": "deleteSpecifications",
   "controller": "collection",
-  "result": {}
+  "result": true
 }
 ```
 
 Deletes the validation specification set for the <index>/<collection>.
 It responds 200 even there where no validation specification manually set before.
 
-***Note:*** by default, an empty specification is implicitally applied to all collections which. In a way, "no specification set" means "all documents are valid". This is why, using this route when no specifications have been set before, does not produce an error.
+***Note:*** by default, an empty specification is implicitly applied to all collections. In a way, "no specification set" means "all documents are valid". This is why, using this route when no specifications have been set before, does not produce an error.

src/sdk-reference/collection/delete-specifications.md

@@ -0,0 +1,96 @@
+---
+layout: side-code.html
+language-tab:
+  js: Javascript
+  java: Android
+  php: PHP
+algolia: true
+title: deleteSpecifications
+---
+
+# deleteSpecifications
+
+```js
+// Deleting specifications using callbacks (NodeJS or Web Browser)
+kuzzle
+  .collection('collection', 'index')
+  .deleteSpecifications(function (err, res) {
+    // callback called once the delete action has been completed
+  });
+
+// Deleting specifications using promises (NodeJS)
+kuzzle
+  .collection('collection', 'index')
+  .deleteSpecificationsPromise()
+  .then(res => {
+    // promises resolved once the delete action has been completed
+  });
+```
+
+```java
+// Deleting one document
+kuzzle
+  .collection("collection", "index")
+  .deleteSpecifications(new ResponseListener<JSONObject>() {
+    @Override
+    public void onSuccess(JSONObject result) {
+
+    }
+
+    @Override
+    public void onError(JSONObject error) {
+      // Handle error
+    }
+  });
+```
+
+```php
+<?php
+
+use \Kuzzle\Kuzzle;
+
+$kuzzle = new Kuzzle('localhost');
+$dataCollection = $kuzzle->collection('collection', 'index');
+
+// Deleting one document
+try {
+  $result = $dataCollection->deleteSpecifications();
+}
+catch (ErrorException $e) {
+
+}
+```
+
+> Callback response:
+
+```json
+{
+  "acknowledged": true
+}
+```
+
+Delete specifications linked to the collection object.
+
+---
+
+## deleteSpecifications([options], [callback])
+
+| Arguments | Type | Description |
+|---------------|---------|----------------------------------------|
+| ``options`` | JSON object | Optional parameters |
+| ``callback`` | function | Optional callback |
+
+---
+
+## Options
+
+| Option | Type | Description | Default |
+|---------------|---------|----------------------------------------|---------|
+| ``queuable`` | boolean | Mark this request as (not) queuable | ``true`` |
+| ``refresh`` | string | If set to ``wait_for``, Kuzzle will wait the persistence layer indexation to return (available with Elasticsearch 5.x and above) | ``undefined`` |
+
+---
+
+## Return value
+
+Returns the `Collection` object to allow chaining.

src/sdk-reference/collection/get-specifications.md

@@ -0,0 +1,98 @@
+---
+layout: side-code.html
+language-tab:
+  js: Javascript
+  java: Android
+  php: PHP
+algolia: true
+title: getSpecifications
+---
+
+# getSpecifications
+
+```js
+// Using callbacks (NodeJS or Web Browser)
+kuzzle
+  .collection('collection', 'index')
+  .getSpecifications(function (error, specifications) {
+    // specifications is a JSON object
+  });
+
+// Using promises (NodeJS)
+kuzzle
+  .collection('collection', 'index')
+  .getSpecificationsPromise()
+  .then(specifications => {
+    // specifications is a JSON object
+  });
+```
+
+```java
+kuzzle
+  .collection("collection", "index")
+  .getSpecifications(new ResponseListener<JSONObject>() {
+    @Override
+    public void onSuccess(JSONObject specifications) {
+        // specifications is a JSONObject
+    }
+
+    @Override
+    public void onError(JSONObject error) {
+      // Handle error
+    }
+  });
+```
+
+```php
+<?php
+
+use \Kuzzle\Kuzzle;
+
+$kuzzle = new Kuzzle('localhost');
+$dataCollection = $kuzzle->collection('collection', 'index');
+
+try {
+  $specifications = $dataCollection->getSpecifications();
+}
+catch (ErrorException $e) {
+
+}
+```
+
+> Callback response
+
+```json
+{
+  "validation": {
+    "strict": "true",
+      "fields": {
+        "foo": {
+          "mandatory": "true",
+          "type": "string",
+          "defaultValue": "bar"
+        }
+      }
+    },
+  "index": "index",
+  "collection": "collection"
+}
+```
+
+Retrieves the specifications linked to the collection object.
+
+---
+
+## getSpecifications([options], callback)
+
+| Arguments | Type | Description |
+|---------------|---------|----------------------------------------|
+| ``options`` | JSON Object | Optional parameters |
+| ``callback`` | function | Callback handling the response |
+
+---
+
+## Options
+
+| Option | Type | Description | Default |
+|---------------|---------|----------------------------------------|---------|
+| ``queuable`` | boolean | Mark this request as (not) queuable | ``true`` |

src/sdk-reference/collection/scroll-specifications.md

@@ -0,0 +1,116 @@
+---
+layout: side-code.html
+language-tab:
+  js: Javascript
+  java: Android
+  php: PHP
+algolia: true
+title: scrollSpecifications
+---
+
+# scrollSpecifications
+
+```js
+// Using callbacks (NodeJS or Web Browser)
+kuzzle
+  .collection('collection', 'index')
+  .scrollSpecifications(scrollId, {scroll: '1m'}, function (err, res) {
+    res.hits.forEach(function (specification) {
+      console.log(specification);      
+    });
+
+    res.total // Total specifications count
+  });
+
+// Using promises (NodeJS only)
+kuzzle
+  .collection('collection', 'index')
+  .scrollSpecificationsPromise(scrollId, {scroll: '1m'})
+  .then(res => {
+    res.hits.forEach(specification => {
+      console.log(specification);
+    });
+
+    res.total // Total specifications count
+  });
+```
+
+```java
+Options opts = new Options();
+opts.setScroll("1m");
+
+kuzzle
+  .collection("collection", "index")
+  .scrollSpecifications(scrollId, opts, new ResponseListener<JSONObject>() {
+    @Override
+    public void onSuccess(JSONObject res) {
+      for (int i = 0; i < res.getJSONArray("hits").length(); i++) {
+          res.getJSONArray("hits").getJSONObject(i) // Specification
+      }
+
+      res.getString("total"); // Total specifications count
+    }
+
+    @Override
+    public void onError(JSONObject error) {
+      // Handle error
+    }
+  });
+```
+
+```php
+<?php
+
+use \Kuzzle\Kuzzle;
+
+$kuzzle = new Kuzzle('localhost');
+$dataCollection = $kuzzle->collection('collection', 'index');
+
+try {
+  $res = $dataCollection->scrollSpecifications($scrollId, ['scroll' => '1m']);
+
+  foreach ($res['hits'] as $specification) {
+    // Specification
+  }
+
+  // Total specifications count
+  $res['total'];
+}
+catch (ErrorException $e) {
+
+}
+```
+
+> Callback response
+
+```json
+{
+  "hits": [
+    {"first": "specification"},
+    {"second": "specification"}
+  ],
+  "total": 2
+}
+```
+
+Returns a JSON object containing the next page of the scroll session, and the `scrollId` to be used by the next `scroll` action.  
+A scroll session is always initiated by a `searchSpecification` action by using the `scroll` argument.
+
+---
+
+## scrollSpecifications(scrollId, [options], callback)
+
+| Arguments | Type | Description |
+|---------------|---------|----------------------------------------|
+| ``scrollId`` | string | The "scrollId" provided with the last scrollSpecifications response or from the initial searchSpecifications request |
+| ``options`` | JSON object | Optional parameters |
+| ``callback`` | function | Callback handling the response |
+
+---
+
+## Options
+
+| Option | Type | Description | Default |
+|---------------|---------|----------------------------------------|---------|
+| ``queuable`` | boolean | Mark this request as (not) queuable | ``true`` |
+| ``scroll`` | string | Re-initializes the scroll session timeout to its value. If not defined, the scroll timeout is defaulted to a Kuzzle configuration | ``undefined`` |