geode-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dbar...@apache.org
Subject geode git commit: GEODE-2352 Document that REST API requires two properties
Date Mon, 08 May 2017 20:40:42 GMT
Repository: geode
Updated Branches:
  refs/heads/develop 5d5f1fb45 -> b9bceb80e


GEODE-2352 Document that REST API requires two properties


Project: http://git-wip-us.apache.org/repos/asf/geode/repo
Commit: http://git-wip-us.apache.org/repos/asf/geode/commit/b9bceb80
Tree: http://git-wip-us.apache.org/repos/asf/geode/tree/b9bceb80
Diff: http://git-wip-us.apache.org/repos/asf/geode/diff/b9bceb80

Branch: refs/heads/develop
Commit: b9bceb80ec498e3643e834f1ef9bfa4096dac42f
Parents: 5d5f1fb
Author: Dave Barnes <dbarnes@pivotal.io>
Authored: Fri May 5 14:11:10 2017 -0700
Committer: Dave Barnes <dbarnes@pivotal.io>
Committed: Mon May 8 13:40:25 2017 -0700

----------------------------------------------------------------------
 .../rest_apps/chapter_overview.html.md.erb      | 13 +++++++--
 geode-docs/rest_apps/rest_prereqs.html.md.erb   | 12 ++++----
 geode-docs/rest_apps/setup_config.html.md.erb   | 29 ++++++++++++++------
 3 files changed, 37 insertions(+), 17 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/geode/blob/b9bceb80/geode-docs/rest_apps/chapter_overview.html.md.erb
----------------------------------------------------------------------
diff --git a/geode-docs/rest_apps/chapter_overview.html.md.erb b/geode-docs/rest_apps/chapter_overview.html.md.erb
index 5e48675..8f29c08 100644
--- a/geode-docs/rest_apps/chapter_overview.html.md.erb
+++ b/geode-docs/rest_apps/chapter_overview.html.md.erb
@@ -21,11 +21,20 @@ limitations under the License.
 
 By using the Geode REST application interface, you can immediately access Geode's data management
capabilities in languages other than the natively supported Java language.
 
-You can write REST-enabled client applications for Geode in a variety of languages that use
the open and standard HTTP protocol-- for example, Ruby, Python, JavaScript and Scala, as
well as already supported languages such as Java.
+You can write REST-enabled client applications for Geode in a variety of languages that use
the open
+and standard HTTP protocol&mdash;for example, Ruby, Python, JavaScript and Scala&mdash;as
well as
+already supported languages such as Java.
 
 When you access Geode through the REST interface, objects are stored in Geode as PdxInstances.
A PdxInstance is a light-weight wrapper around PDX serialized bytes. It provides applications
with run-time access to fields of a PDX serialized object. This interoperable format allows
your Java applications to operate on the same data as your REST applications.
 
-As an added benefit, because Geode's REST interface stores objects as PdxInstances, you do
not need to write corresponding Java classes to translate JSON data (which you must do with
other REST interface providers such as Oracle Coherence.) For example, consider the use case
where a non-Java REST client application (Python, Ruby or Scala) performs Geode region operations
with JSON data that represents employee data. Since the object is stored in Geode as a PdxInstance
that can be automatically mapped to JSON, the user does not need to write a corresponding
Employee.java class and also does not need to worry about related issues such as keeping the
Employee object in the CLASSPATH.
+As an added benefit, because Geode's REST interface stores objects as PdxInstances, you do
not need
+to write corresponding Java classes to translate JSON data (which you must do with other
REST
+interface providers such as Oracle Coherence). For example, consider the use case where a
non-Java
+REST client application (Python, Ruby or Scala) performs Geode region operations with JSON
data that
+represents employee data. Since the object is stored in Geode as a PdxInstance that can be
+automatically mapped to JSON, the user does not need to write a corresponding Employee.java
class
+and also does not need to worry about related issues such as keeping the Employee object
in the
+CLASSPATH.
 
 See [Geode PDX Serialization](../developing/data_serialization/gemfire_pdx_serialization.html#gemfire_pdx_serialization)
for more information on PDX serialization.
 

http://git-wip-us.apache.org/repos/asf/geode/blob/b9bceb80/geode-docs/rest_apps/rest_prereqs.html.md.erb
----------------------------------------------------------------------
diff --git a/geode-docs/rest_apps/rest_prereqs.html.md.erb b/geode-docs/rest_apps/rest_prereqs.html.md.erb
index 935f94b..55fe050 100644
--- a/geode-docs/rest_apps/rest_prereqs.html.md.erb
+++ b/geode-docs/rest_apps/rest_prereqs.html.md.erb
@@ -19,19 +19,19 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-Before development, understand the prerequisites and limitations of the current REST implementation
in Geode.
+Before development, it is important to understand the prerequisites and limitations of the
Geode REST implementation.
 
 Geode and REST-enabled applications accessing Geode are subject to the following rules and
limitations:
 
 -   All domain objects, functions and function-arg classes must be properly configured and
registered in the Geode deployment. Any functions that you wish to execute through the REST
API must be available on the target member’s CLASSPATH.
--   The current implementation only supports the **application/json** MIME type. At time
of publication, any other return types (XML, objects, and so on) are not supported. Plain
text is supported as a return type for some error messages.
--   Keys are strictly of type String for this release. For example, the request `PUT http://localhost:8080/gemfire-api/v1/customers/123.456`
will add entry for key ("123.456") of type String.
+-   The current implementation supports only the **application/json** MIME type. Other return
types (XML, objects, and so on) are not supported. Plain text is supported as a return type
for some error messages.
+-   Keys are strictly of type String. For example, the request `PUT http://localhost:8080/gemfire-api/v1/customers/123.456`
will add an entry for key ("123.456") of type String.
 -   Some special formats of JSON documents are not supported in Geode REST. See [Key Types
and JSON Support](troubleshooting.html#concept_gsv_zd5_m4) for examples.
 -   To achieve interoperability between Geode Java clients (or Geode native clients) and
REST clients, the following rules must be followed:
-    -   All Geode Java and native client classes operating on data also accessed by the REST
interface must be PDX serialized either via PDX autoserialization or by implementing `PdxSerializable`.
-    -   Geode Java clients and native clients can retrieve REST-enabled data either as a
`PdxInstance` or as an actual object by using the `PdxInstance.getObject` method. If you use
the latter method, first you must declare the object type (@type) in your POST or PUT request
payload when creating the object in REST; and secondly, the Java client must have the actual
domain class in its CLASSPATH.
+    -   All Geode Java and native client classes operating on data also accessed by the REST
interface must be PDX serialized, either via PDX autoserialization or by implementing `PdxSerializable`.
+    -   Geode Java clients and native clients can retrieve REST-enabled data either as a
`PdxInstance` or as an actual object by using the `PdxInstance.getObject` method. If you use
the latter method, you must first declare the object type (@type) in your POST or PUT request
payload when creating the object in REST; and secondly, the Java client must have the actual
domain class in its CLASSPATH.
 -   Objects returned by REST-invoked functions must be returned as PdxInstance objects or
other data types that can be written to JSON. You cannot return Java objects.
 -   REST client applications do not support single hop access or notification features.
--   Specifying subregions as endpoints is not currently supported.
+-   Specifying subregions as endpoints is not supported.
 
 

http://git-wip-us.apache.org/repos/asf/geode/blob/b9bceb80/geode-docs/rest_apps/setup_config.html.md.erb
----------------------------------------------------------------------
diff --git a/geode-docs/rest_apps/setup_config.html.md.erb b/geode-docs/rest_apps/setup_config.html.md.erb
index 71c50f5..566b1a2 100644
--- a/geode-docs/rest_apps/setup_config.html.md.erb
+++ b/geode-docs/rest_apps/setup_config.html.md.erb
@@ -21,18 +21,23 @@ limitations under the License.
 
 The Apache Geode developer REST interface runs as an embedded HTTP or HTTPS service (Jetty
server) within a Geode data node.
 
-All Geode REST interface classes and required JAR files are distributed as a WAR file with
the Geode product distribution. You can locate the file in the following location:
+All Geode REST interface classes and required JAR files are distributed as a WAR file with
the Geode product distribution. You can find the file in the following location:
 
-``` pre
-$GEMFIRE/tools/Extensions/gemfire-api.war
-```
+<code>
+<i>install-dir</i>/tools/Extensions/geode-web-api-<i>n.n.n.</i>war
+</code>
+
+where _install-dir_ is the server installation directory and _n.n.n_ is a version number.
 
 To enable the developer REST API service in Apache Geode, set the `start-dev-rest-api` Geode
property to `true` when starting a data node using either `gfsh` or the ServerLauncher API.
Setting this property to true on a data node will start up an embedded Jetty server and deploy
the REST developer API WAR file.
 
 **Note:**
-The REST API service for application development can only be started on servers; you cannot
use locators to host the developer Geode REST API services.
+The REST API service for application development runs only on servers; you cannot use locators
to host the developer Geode REST API services.
 
-You can have multiple REST enabled data nodes in a single distributed system. Each data node
should have a separate host name and unique end point. To ensure that the data node is reachable
on a machine with multiple NIC addresses, you can use `http-service-bind-address` to bind
an address to the REST API service (as well as the other embedded web services such as Pulse.)
+You can have multiple REST enabled data nodes in a single distributed system. Each data node
should
+have a separate host name and unique end point. To ensure that the data node is reachable
on a
+machine with multiple NIC addresses, you can use `http-service-bind-address` to bind an address
to
+the REST API service (as well as the other embedded web services such as Pulse).
 
 You can also configure the Developer REST API service to run over
 HTTPS by enabling ssl for the `http` component in `gemfire.properties`
@@ -75,15 +80,21 @@ The following procedure starts up a REST API service-enabled Geode deployment:
 
     After you have configured PDX for your caches, then proceed with starting up your REST-enabled
servers and other data nodes.
 
-2.  Start a server node with the Geode property `start-dev-rest-api` set to `true`. For example:
+2.  Start a server node with the Geode property `start-dev-rest-api` set to `true`. 
+    Optionally, you can also configure a `http-service-bind-address` and `http-service-port`
to
+    identify the cache server and specific port that will host REST services. If you do not
specify
+    the `http-service-port`, the default port is 7070. If you do not specify
+    `http-service-bind-address`, the HTTP service will bind to all local addresses by default.
+    **Note:** If your application will be running in a VM (as when running in the cloud,
for example), it's good practice to specify `http-service-bind-address` and `http-service-port`
+    so they will be publicly visible. The default values may not be visible outside the VM
in which the application is running.
+
+    For example:
 
     ``` pre
     gfsh>start server --name=server1 --start-rest-api=true \
     --http-service-port=8080 --http-service-bind-address=localhost
     ```
 
-    Optionally, you can also configure a `http-service-bind-address` and `http-service-port`
to identify the cache server and specific port that will host REST services. If you do not
specify the `http-service-port`, the default port is 7070. If you do not specify `http-service-bind-address`,
the HTTP service will bind to all local addresses by default.
-
     Any server that hosts data, even a server acting as a JMX manager, can start the developer
REST API service. For example, to start the service on a server that is also a JMX manager,
you would run:
 
     ``` pre


Mime
View raw message