You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by dm...@apache.org on 2020/09/17 22:37:37 UTC
[ignite] branch IGNITE-7595 updated: update the REST API doc
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 <dm...@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: