This is an automated email from the ASF dual-hosted git repository. dmagda pushed a commit to branch IGNITE-7595 in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/IGNITE-7595 by this push: new 8b52d96 update the REST API doc 8b52d96 is described below commit 8b52d96ad573ee757ec427f2b6a1e54aa98c87d8 Author: Denis Magda <dma...@gridgain.com> AuthorDate: Thu Sep 17 15:37:17 2020 -0700 update the REST API doc --- docs/_docs/restapi.adoc | 113 +++++++++++++++++++++++++++--------------------- 1 file changed, 64 insertions(+), 49 deletions(-) diff --git a/docs/_docs/restapi.adoc b/docs/_docs/restapi.adoc index 000e626..91ee281 100644 --- a/docs/_docs/restapi.adoc +++ b/docs/_docs/restapi.adoc @@ -169,12 +169,13 @@ To set a custom expire time, set the system variable: `IGNITE_REST_SESSION_TIMEO ==== == Data Types -The REST API also supports <<Java built-in types>> and <<Custom user defined types>> for put/get operations via `keyType` and `valueType` optional parameters. +By default, the REST API exchanges query parameters in the `String` format. The cluster works with the parameters as +with `String` objects. -Note that unless one of the types mentioned below is explicitly specified, the REST protocol will exchange the key-value data in `String` format. -This means that the data is stored and retrieved to/from the cluster as a `String`. +If a type of a parameter is different from `String`, you can use the `keyType` or `valueType` to specify the real type +of the argument. The REST API supports both <<Java Types>> and <<Custom Types>>. -=== Java built-in types +=== Java Types [width="100%", cols="50%,50%"] |======= @@ -243,71 +244,85 @@ Similarly, the `get` command with `keyType=int` and `valueType=date` would be: http://[host]:[port]/ignite?cmd=get&key=1&cacheName=myCache&keyType=int&valueType=date ---- -=== Custom user defined types +=== Custom Types + +The JSON format is used to exchange complex custom objects via the Ignite REST protocol. + +For example, let's assume you have a `Person` class, and below is the JSON representation of an object instance that +you need to send to the cluster: -For custom objects, the JSON format is used. For example, we can work with the following object using the REST API: [source,javascript] +---- { - "uid": "7e51118b-eb15-4373-b57f-4984cb9cd7ac", + "uid": "7e51118b", "name": "John Doe", "organization": 5678901, "married": false, "salary": 156.1 } +---- -The following request puts this object into the cache named 'testCache' as a value with a type name `Person` and a key `1`. - - http://[host]:[port]/ignite?cacheName=testCache&cmd=put&keyType=int&key=1&valueType=Person&val=%7B%0A+++++%22uid%22%3A+%227e51118b-eb15-4373-b57f-4984cb9cd7ac%22%2C%0A+++++%22name%22%3A+%22John+Doe%22%2C%0A+++++%22organization%22%3A+5678901%2C%0A+++++%22married%22%3A+false%2C%0A+++++%22salary%22%3A+156.1%0A++%7D& +Next, you use this REST request to put the object in the cluster by setting the `valueType` parameter to `Person` and +the `val` parameter to the value of the JSON object: -On the server side, the JSON value from this request will be converted to link:/docs/data-modeling/data-modeling#binary-object-format[binary object]. Field types are resolved in the following order: +[source,text] +---- +http://[host]:[port]/ignite?cacheName=testCache&cmd=put&keyType=int&key=1&valueType=Person +&val=%7B%0A+++++%22uid%22%3A+%227e51118b%22%2C%0A+++++%22name%22%3A+%22John+Doe%22%2C%0A+++++%22organization%22%3A+5678901%2C%0A+++++%22married%22%3A+false%2C%0A+++++%22salary%22%3A+156.1%0A++%7D& +---- -* If the type name is a `Java class` available on the server, the class field types with corresponding names will be used for resolving JSON object field types. -* If the type name is of a `query entity` type, the field types will be resolved according to the field type defined in the `query entity`. -* Otherwise, the field types will be resolved according to regular JSON types. +Once a server receives the request, it converts the object from the JSON into the internal +link:/docs/data-modeling/data-modeling#binary-object-format[binary object] format following the conversion procedure below: -For example, if there is no definition of the "Person" type on the server, the fields will be converted in accordance with the standard JSON types: -[source,javascript] -"uid": "7e51118b-eb15-4373-b57f-4984cb9cd7ac", // string -"name": "John Doe", // string -"organization": 5678901, // int -"married": false, // boolean -"salary": 156.1 // double +* If the `Person` class exists and available on the server's classpath, the JSON object is resolved to an instance of the `Person` class. -If the `query entity` is set or `Java class` "Person" is loaded on the server. +* If the `Person` class is not available on the server’s classpath, but there is a `QueryEntity` object that defines +the `Person`, then the JSON object is resolved to a binary object of that `Person` type: ++ [%header, cols="2"] |=== -|Query entity|Java class -a|[source,xml] +|Query entity|Binary Object (Person) +a| +[source,xml] +---- <bean class="org.apache.ignite.cache.QueryEntity"> - <property name="keyType" value="java.lang.Integer"/> - <property name="valueType" value="Person"/> - <property name="fields"> - <map> - <entry key="uid" value="java.util.UUID"/> - <entry key="name" value="java.lang.String"/> - <entry key="organization" value="java.lang.Long"/> - <entry key="married" value="java.lang.Boolean"/> - <entry key="salary" value="java.lang.Float"/> - </map> - </property> +<property name="keyType" value="java.lang.Integer"/> +<property name="valueType" value="Person"/> +<property name="fields"> +<map> +<entry key="uid" value="java.util.UUID"/> +<entry key="name" value="java.lang.String"/> +<entry key="organization" value="java.lang.Long"/> +<entry key="married" value="java.lang.Boolean"/> +<entry key="salary" value="java.lang.Float"/> +</map> +</property> </bean> -a|[source,java] -class Person { - UUID uid; - String name; - long organization; - boolean married; - float salary; -} +---- +a| +[source,javascript] +---- + "uid": "7e51118b", // UUID + "name": "John Doe", // string + "organization": 5678901, // long + "married": false, // boolean + "salary": 156.1 // float +---- |=== -The fields of the object will be of the following types: +* Otherwise, the JSON object’s field types are resolved following the regular JSON convention: ++ [source,javascript] - "uid": "7e51118b-eb15-4373-b57f-4984cb9cd7ac", // UUID - "name": "John Doe", // string - "organization": 5678901, // long - "married": false, // boolean - "salary": 156.1 // float +---- +"uid": "7e51118b", // string +"name": "John Doe", // string +"organization": 5678901, // int +"married": false, // boolean +"salary": 156.1 // double +---- + +The same conversion rules apply when you have a custom key type set via the `keyType` parameter of the Ignite +REST protocol. == Returned Value The HTTP REST request returns a JSON object which has a similar structure for each command: