geode-docs/rest_apps/develop_rest_apps.html.md.erb - geode - Git at Google

 ---
 title: Developing REST Applications
 ---

 <!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 -->
 <a id="topic_lvp_cd5_m4"></a>


 This section provides guidelines on writing REST client applications for <%=vars.product_name%>.

 You can browse, query, update and delete data stored in your <%=vars.product_name%> deployment. You can also manage and execute pre-deployed functions on <%=vars.product_name%> members.

 -   **[Working with Regions](#topic_qhs_f25_m4)**

     The <%=vars.product_name%> REST APIs provide basic CRUD (create, read, update and delete) operations for data entries stored in your regions.

 -   **[Working with Queries](#topic_fcn_g25_m4)**

     <%=vars.product_name%> supports the use of queries to extract data from its regions. Using REST APIs, you can create and execute either prepared or ad-hoc queries on <%=vars.product_name%> regions. You can also update and delete prepared queries.

 -   **[Working with Functions](#topic_rbc_h25_m4)**

     <%=vars.product_name%> REST APIs support the discovery and execution of predefined <%=vars.product_name%> functions on your cluster deployments.

 ## <a id="topic_qhs_f25_m4" class="no-quick-link"></a>Working with Regions

 The <%=vars.product_name%> REST APIs provide basic CRUD (create, read, update and delete) operations for data entries stored in your regions.

 Regions are the resources of the <%=vars.product_name%> REST API. Each region represents a resource or a collection of resources.

 You cannot create or delete the regions themselves with the REST APIs, but you can work with the data stored within predefined <%=vars.product_name%> regions. Use the [gfsh](../tools_modules/gfsh/chapter_overview.html) command utility to add, configure or delete regions in your <%=vars.product_name%> deployment. Any additions or modifications to regions made through `gfsh` are then accessible by the REST APIs.

 ## Listing Available Regions

 The main resource endpoint to the <%=vars.product_name%> API is [GET /geode/v1](get_regions.html#topic_itv_mg5_m4). Use this endpoint to discover which regions are available in your cluster.

 Example call:

 ``` pre
 curl -i http://localhost:7070/geode/v1
 ```

 Example response:

 ``` pre
 Accept: application/json
 Response Payload: application/json

 200 OK
 Server: Apache-Coyote/1.1
 Location: http://localhost:7070/geode/v1
 Content-Type: application/json
 Transfer-Encoding: chunked
 Date: Sat, 18 Jan 2014 20:05:47 GMT
 {
     "regions": [
         {
             "name": "customers",
             "type": "REPLICATE",
             "key-constraint": "java.lang.String",
             "value-constraint": "org.apache.geode.pdx.PdxInstance"
         },
         {
             "name": "items",
             "type": "REPLICATE",
             "key-constraint": null,
             "value-constraint": null
         },
         {
             "name": "orders",
             "type": "PARTITION",
             "key-constraint": null,
             "value-constraint": null
         },
         {
             "name": "primitiveKVStore",
             "type": "PARTITION",
             "key-constraint": null,
             "value-constraint": null
         },
         {
             "name": "empty_region",
             "type": "EMPTY",
             "key-constraint": "java.lang.String",
             "value-constraint": "org.apache.geode.pdx.PdxInstance"
         }
     ]
 }
 ```

 Each region listed in the response includes the following region attributes:

 -   **name**. Name of the region.
 -   **type**. Type of region. For example, REPLICATE, PARTITION, or EMPTY. See [Region Types](../developing/region_options/region_types.html#region_types) for more information.
 -   **key-constraint**. If defined, the fully qualified class name of the key's type. Otherwise, null.
 -   **value-constraint**. If defined, the fully qualified class name of the value's type. Otherwise, null.

 If no resources (regions) are available in the cluster, the call returns a 404 NOT FOUND error.

 ## Reading Region Data

 You can read data from a region by using any of the following REST-enabled mechanisms:

 -   **GET /geode/v1/{region}?limit=ALL** - Read all entries in a region
 -   **GET /geode/v1/{region}?limit=*N*** - Read a limited number of entries in a region
 -   **GET /geode/v1/{region}/keys** - List all keys in a region
 -   **GET /geode/v1/{region}/{keys}** - Read data for specific key or keys in a region

 **Reading Entries**

 To read entries in a region, use the following REST endpoint:

 ``` pre
 GET /geode/v1/{region}?[limit={<number>|ALL}]
 ```

 For example:

 ``` pre
 http://localhost:7070/geode/v1/items
 ```

 To read all entries in the region, specify instead:

 ``` pre
 http://localhost:7070/geode/v1/items?limit=ALL
 ```

 To read 80 entries from the region, specify:

 ``` pre
 http://localhost:7070/geode/v1/items?limit=80
 ```

 Setting the limit parameter is optional. If you do not specify a limit, the request will return 50 results by default. The returned order of the results is not guaranteed; however, the response values (JSON) are specified in the same order as the list of comma-separated keys returned in the "Content-location" header.

 **Reading Keys**

 To list all keys in a region, use the following endpoint:

 ``` pre
 /geode/v1/{region}/keys
 ```

 For example:

 ``` pre
 http://localhost:7070/geode/v1/items/keys
 ```

 You can use the returned key to perform additional operations on the keys such as read, update or delete their values.

 **Reading Entries By Key**

 To obtain data for a specific key or set of keys, use the following endpoints:

 ``` pre
 GET /geode/v1/{region}/{key1}
 ```

 or

 ``` pre
 GET /geode/v1/{region}/{key1},{key2},...,{keyN}
 ```

 where you specify keys in a comma-delimited list.

 For example:

 ``` pre
 http://localhost:7070/geode/v1/items/1

 http://localhost:7070/geode/v1/items/1,3,5
 ```

 If one or more of the keys you provide in the list of keys is missing from the region, you will receive a 400 BAD STATUS error response.

 If you are providing multiple keys, you can also use the `ignoreMissingKey=true` parameter to prevent 400 errors. Any non-existing keys will instead return a null response. For example:

 ``` pre
 http://localhost:7070/geode/v1/items/1,3,5?ignoreMissingKey=true
 ```

 ## Adding or Modifying Region Data

 To add data to a region, you have several options:

 -   Create new a brand new entry (both key and value) in a region
 -   Update or insert a value for a key (if the key does not exist, it will be created)
 -   Update (replace) data for a key if and only if the key already exists in region
 -   Compare existing value for a key before replacing value
 -   Update or insert multiple values in the region for a set of provided keys

 **Adding entries**

 To add a new key and value to a region, you can use the following endpoint:

 ``` pre
 POST /geode/v1/{region}?key=<key>
 ```

 This endpoint only puts the entry into the region **if the specified key does not already exist**. If the key already exists, the request will fail with a 409 CONFLICT error.

 **Note:**
 If you do not specify a key for this request, a String representation of a numerical key will be generated automatically for you.

 Specify the value for the new entry in the request body. For example:

 ``` pre
 http://localhost:7070/geode/v1/orders?key=2
 ```

 ``` pre
 Request Payload: application/json
 POST /geode/v1/orders?key=2

 Accept: application/json
 Content-Type: application/json
 {
     "@type":  "org.apache.geode.web.rest.domain.Order",
      "purchaseOrderNo": 112,
      "customerId": 1012,
      "description":  "Purchase Order for myCompany",
      "orderDate":  "02/10/2014",
      "deliveryDate":  "02/20/2014",
      "contact":  "John Doe",
      "email":  "John.Doe@example.com",
      "phone":  "01-2048096",
      "totalPrice": 225,
      "items": [
         {
              "itemNo": 1,
              "description":  "Product2, PartA",
              "quantity": 10,
              "unitPrice": 5,
              "totalPrice": 50
         },
         {
              "itemNo": 2,
              "description":  "Product2, PartB",
              "quantity": 20,
              "unitPrice": 20,
              "totalPrice": 400
         }
     ]
 }
 ```

 Note that in the example above, `@type` is used to declare the value-constraint for the new entry. This declaration is required to provide interoperability between Java cache clients and REST clients.

 Alternately, you can also use the following endpoint to create a new entry:

 ``` pre
 PUT /gemfire/v1/{region}/{key}
 ```

 This endpoint will add the entry if the key does not exist. If the key already exists, the operation will update the entry.

 ``` pre
 http://localhost:7070/geode/v1/orders/2
 ```

 ``` pre
 Request Payload: application/json
 PUT /geode/v1/orders/2
 Request Payload: application/json
 Content-Type: application/json
 Accept: application/json
 {
     "@type": "org.apache.geode.web.rest.domain.Order",
      "purchaseOrderNo": 1121,
      "customerId": 1012,
      "description":  "Order for XYZ Corp",
      "orderDate":  "02/10/2014",
      "deliveryDate":  "02/20/2014",
      "contact":  "Pie Doe",
      "email":  "pie.doe@example.com",
      "phone":  "01-2048096",
      "totalPrice": 225,
      "items": [
         {
              "itemNo": 1,
              "description": "Product-100",
              "quantity": 10,
              "unitPrice": 5,
              "totalPrice": 50
         }
     ]
 }
 ```

 **Modifying existing entries**

 <%=vars.product_name%> provides three different options for this type of operation. To update a value for the key, you can use:

 ``` pre
 PUT /gemfire/v1/{region}/{key}
 PUT /gemfire/v1{region}/{key}?op=REPLACE
 PUT /gemfire/v1{region}/{key}?op=CAS
 ```

 If you do not specify a parameter to the PUT operation, the request which will add or update the entry regardless of whether the key already exists in the region. See the example above.

 ``` pre
 http://localhost:7070/geode/v1/orders/2
 ```

 If you specify the op=REPLACE parameter, the request which will explicitly perform a Cache replace operation and will verify that the key exists before replacing the value. If the key does not exist in the specified region, you will receive a 404 NOT FOUND error. This operation is idempotent, meaning multiple identical requests will have the same effect as the initial request.

 ``` pre
 http://localhost:7070/geode/v1/orders/2?op=REPLACE
 ```

 If you specify the op=CAS parameter, the value will only be replaced with the `@new` value only if the specified `@old` value matches the current value of the key in the region. If the `@old` value does not match the current value, then a 409 CONFLICT error is thrown. If you receive a 409 CONFLICT error, you can call the `GET /geode/v1/{region}/{key}` endpoint to get an updated copy of the value. This operation is not idempotent and multiple identical requests will not have the same effect as the initial request. You can use this type of REST call to achieve a similar effect as optimistic locking.

 ``` pre
 http://localhost:7070/geode/v1/orders/2?op=REPLACE
 ```

 ``` pre
 Request Payload: application/json

 PUT /geode/v1/orders/2?op=CAS

 Accept: application/json
 Content-Type: application/json
 {
     "@old": {
          "@type":  "org.apache.geode.web.rest.domain.Order",
          "purchaseOrderNo": 1121,
          "customerId": 1012,
          "description":  "Order for  XYZ Corp",
          "orderDate":  "02/10/2014",
          "deliveryDate":  "02/20/2014",
          "contact":  "Jelly Bean",
          "email":  "jelly.bean@example.com",
          "phone":  "01-2048096",
          "items": [
             {
                  "itemNo": 1,
                  "description":  "Product-100",
                  "quantity": 12,
                  "unitPrice": 5,
                  "totalPrice": 60
             }
         ],
          "totalPrice": 225
     },
      "@new ": {
          "@type":  "org.apache.geode.web.rest.domain.Order",
          "purchaseOrderNo": 1121,
          "customerId": 1013,
          "description":  "Order for  New Corp",
          "orderDate":  "02/10/2014",
          "deliveryDate":  "02/25/2014",
          "contact":  "Vanilla Bean",
          "email":  "vanillabean@example.com",
          "phone":  "01-2048096",
          "items": [
             {
                  "itemNo": 12345,
                  "description":  "part 123",
                  "quantity": 12,
                  "unitPrice": 29.99,
                  "totalPrice": 149.95
             }
         ],
          "totalPrice": 149.95
     }
 }
 ```

 **Adding or updating multiple values for a set of keys**

 To update multiple values for keys, use:

 ``` pre
 PUT /geode/v1/{region}/{key1},{key2},...,{keyN}
 ```

 This REST call will update any keys that already exist and insert values for any keys that do not exist in the region.

 ## Deleting Region Data

 There are three options for deleting data in a region using REST APIs:

 -   Delete all the data in the region. Limited to replicated regions only; not available for partitioned regions.
 -   Delete the data associated with a particular key
 -   Delete the data associated with a set of keys

 **Deleting all data**

 To delete all data in the region, use the following endpoint:

 ``` pre
 DELETE /geode/v1/{region}
 ```

 For example:

 ``` pre
 http://localhost:7070/geode/v1/items
 ```

 Note that this does not delete the region itself, but instead all the entries in the region.

 **Deleting data based on key**

 Use:

 ``` pre
 DELETE /geode/v1/{region}/{key}
 ```

 or

 ``` pre
 DELETE /geode/v1/{region}/{key}{key1},{key2},...{keyN}
 ```

 If any of the supplied keys are not found in the region, the request will fail and return a 404 NOT FOUND ERROR.

 ## <a id="topic_fcn_g25_m4" class="no-quick-link"></a>Working with Queries

 <%=vars.product_name%> supports the use of queries to extract data from its regions. Using REST APIs, you can create and execute either prepared or ad-hoc queries on <%=vars.product_name%> regions. You can also update and delete prepared queries.

 ## Listing Queries

 To find out which predefined and named queries are available in your deployment, use the following endpoint:

 ``` pre
 GET /geode/v1/queries
 ```

 All queries that have been predefined and assigned IDs in <%=vars.product_name%> are listed.

 ## <a id="topic_fcn_g25_m4__section_t4h_wtp_y4" class="no-quick-link"></a>Creating a New Query

 To create a query, use the following endpoint:

 ``` pre
 POST /geode/v1/queries?id=<queryId>&q=<OQL-statement>
 ```

 Here are some examples:

 ``` pre
 http://localhost:7070/geode/v1/queries?id=selectOffers&q="SELECT DISTINCT c FROM /customers c, /orders o WHERE o.totalprice < $1 AND c.customerId = o.customerId"
 ```

 **Note:**
 The query must be provided as a URL parameter. You cannot specify OQL in the request body at this time.

 You can specify query bind parameters ($1) in your predefined queries and then pass in values at runtime.

 To update this query at a later time, use the [PUT operation](#topic_fcn_g25_m4__section_oj1_b5p_y4) described below.

 ## <a id="topic_fcn_g25_m4__section_b1p_wtp_y4" class="no-quick-link"></a>Executing a Prepared Query

 To run a prepared query, use:

 ``` pre
 POST /geode/v1/queries/{queryId}
 ```

 Specify the queryId in the URL. All query argument must be passed in the request body. For example:

 ``` pre
 http://localhost:7070/geode/v1/queries/selectOrders
 ```

 ``` pre
 Request Payload: OQL bind parameter values HTTP message body of media type application/json
 POST /geode/v1/queries/selectOrders
 Accept: application/json
 Content-Type: application/json

 [
     {
          "@type": "int",
          "@value": 2
     },
     {
          "@type": "double",
          "@value": 110.00
     }
 ]

 Response Payload: application/json

 200 OK
 Content-Length: <#-of-bytes>
 Content-Type: application/json

 [
     {
         "description": "Purchase order for company - B",
         "totalPrice": 350,
         "purchaseOrderNo": 1112,
         "customerId": 102,
         "deliveryDate": "Thu Feb 20 00:00:00 IST 2014",
         "contact": "John Doe",
         "email": "jDoe@example.com",
         "phone": "01-2048096",
         "items": [
             {
                 "description": "Product-AAAA",
                 "quantity": 10,
                 "itemNo": 1,
                 "unitPrice": 20,
                 "totalPrice": 200,
                 "type-class": "org.apache.geode.web.rest.domain.Item"
             },
             {
                 "description": "Product-BBB",
                 "quantity": 15,
                 "itemNo": 2,
                 "unitPrice": 10,
                 "totalPrice": 150,
                 "type-class": "org.apache.geode.web.rest.domain.Item"
             }
         ],
         "orderDate": "Mon Feb 10 00:00:00 IST 2014",
         "type-class": "org.apache.geode.web.rest.domain.Order"
     },
     {...},
     {...}
 }
 ```

 Another example:

 ``` pre
 http://localhost:7070/geode/v1/queries/selectOrders
 ```

 ``` pre
 Request Payload: OQL bind parameter values HTTP message body of media type application/json
 POST /geode/v1/queries/selectCustomer
 Accept: application/json
 Content-Type: application/json
 {
     "args": [
         {
             "@type": "int",
             "@value": 101
         }
     ]
 }

 Response-Payload: application/json

 200 Ok
 Content-Length: 140
 Content-Type: application/json
 [
     {
         "firstName": "Jane",
         "lastName": "Doe",
         "customerId": 101,
         "type-class": "org.apache.geode.web.rest.domain.Customer"
     }
 ]
 ```

 ## <a id="topic_fcn_g25_m4__section_oj1_b5p_y4" class="no-quick-link"></a>Modifying a Prepared Query

 To modify an existing prepared query, use the following endpoint:

 ``` pre
 PUT /geode/v1/queries/{queryId}
 ```

 Here are some examples:

 ``` pre
 http://localhost:7070/geode/v1/queries/selectOffers&q="SELECT DISTINCT c FROM /customers c, /orders o WHERE o.totalprice < $1 AND c.customerId = o.customerId"
 ```

 You can specify query bind parameters ($1) in your predefined queries, and then pass in values at runtime.

 A PUT operation will only succeed if the specified queryId already exists (for example, created with the [POST operation](#topic_fcn_g25_m4__section_t4h_wtp_y4) above.) If the queryId does already exist, you will receive a 404 response - "Named query (selectKey456) does not exist!"

 ## <a id="topic_fcn_g25_m4__section_igg_b5p_y4" class="no-quick-link"></a>Deleting a Prepared Query

 To delete an existing prepared query, use the following endpoint:

 ``` pre
 DELETE /geode/v1/queries/{queryId}
 ```

 ## <a id="topic_fcn_g25_m4__section_wbk_b5p_y4" class="no-quick-link"></a>Executing an Ad-Hoc Query

 To run an unnamed query, use the following endpoint:

 ``` pre
 GET /geode/v1/queries/adhoc?q=<OQL-statement>
 ```

 Provide the OQL query string directly in the URL enclosed in single quotes.

 For example:

 ``` pre
 http://localhost:7070/geode/v1/queries/adhoc?q="SELECT * FROM /customers"
 ```

 ## <a id="topic_rbc_h25_m4" class="no-quick-link"></a>Working with Functions

 <%=vars.product_name%> REST APIs support the discovery and execution of predefined <%=vars.product_name%> functions on your cluster deployments.

 Before you can access functions using REST APIs, you must have already defined and registered the functions in your <%=vars.product_name%> deployment. Additionally, any domain objects that are being accessed by the functions must be available on the CLASSPATH of the server running the REST endpoint service.

 You can do the following with functions:

 -   List all functions available in the <%=vars.product_name%> cluster.
 -   Execute a function, optionally specifying the region and members and/or member groups that are targeted by the function

 ## Listing Functions

 To list all functions that are currently registered and deployed in the <%=vars.product_name%> cluster, use the following endpoint:

 ``` pre
 GET /geode/v1/functions
 ```

 The list of returned functions includes the functionId, which you can use to execute the function as described in the next section.

 ## Executing Functions

 To execute a function on a <%=vars.product_name%> cluster, use the following endpoint:

 ``` pre
 POST /geode/v1/functions/{functionId}?[&onRegion=regionname|&onMembers=member1,member2,...,memberN|&onGroups=group1,group2,...,groupN]
 ```

 You have the option to target a specific region and members or member groups when executing your function. If you do not specify these parameters, the function will execute on all members that are hosting data in the entire cluster by default. Function arguments are passed in the request body.

 For example:

 ``` pre
 http://localhost:7070/geode/v1/functions/AddFreeItemToOrders
 ```

 ``` pre
 Request Payload: application/json
 POST /geode/v1/functions/AddFreeItemToOrders
 Accept: application/json
 Content-Type: application/json

 [
     {
         "@type": "double",
         "@value": 210
     },
     {
         "@type": "org.apache.geode.web.rest.domain.Item",
         "itemNo": "599",
         "description": "Part X Free on Bumper Offer",
         "quantity": "2",
         "unitprice": "5",
         "totalprice": "10.00"
      }
 ]
 ```

 In the above example, the `Item` domain object must be in the CLASSPATH of all members receiving the function. If the object is not defined, the function will fail with an `Internal Server` error. Look for `ClassNotFoundException`s in the stack trace.
	---
	title: Developing REST Applications
	---

	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<a id="topic_lvp_cd5_m4"></a>


	This section provides guidelines on writing REST client applications for <%=vars.product_name%>.

	You can browse, query, update and delete data stored in your <%=vars.product_name%> deployment. You can also manage and execute pre-deployed functions on <%=vars.product_name%> members.

	- [Working with Regions](#topic_qhs_f25_m4)

	The <%=vars.product_name%> REST APIs provide basic CRUD (create, read, update and delete) operations for data entries stored in your regions.

	- [Working with Queries](#topic_fcn_g25_m4)

	<%=vars.product_name%> supports the use of queries to extract data from its regions. Using REST APIs, you can create and execute either prepared or ad-hoc queries on <%=vars.product_name%> regions. You can also update and delete prepared queries.

	- [Working with Functions](#topic_rbc_h25_m4)

	<%=vars.product_name%> REST APIs support the discovery and execution of predefined <%=vars.product_name%> functions on your cluster deployments.

	## <a id="topic_qhs_f25_m4" class="no-quick-link"></a>Working with Regions

	The <%=vars.product_name%> REST APIs provide basic CRUD (create, read, update and delete) operations for data entries stored in your regions.

	Regions are the resources of the <%=vars.product_name%> REST API. Each region represents a resource or a collection of resources.

	You cannot create or delete the regions themselves with the REST APIs, but you can work with the data stored within predefined <%=vars.product_name%> regions. Use the [gfsh](../tools_modules/gfsh/chapter_overview.html) command utility to add, configure or delete regions in your <%=vars.product_name%> deployment. Any additions or modifications to regions made through `gfsh` are then accessible by the REST APIs.

	## Listing Available Regions

	The main resource endpoint to the <%=vars.product_name%> API is [GET /geode/v1](get_regions.html#topic_itv_mg5_m4). Use this endpoint to discover which regions are available in your cluster.

	Example call:

	``` pre
	curl -i http://localhost:7070/geode/v1
	```

	Example response:

	``` pre
	Accept: application/json
	Response Payload: application/json

	200 OK
	Server: Apache-Coyote/1.1
	Location: http://localhost:7070/geode/v1
	Content-Type: application/json
	Transfer-Encoding: chunked
	Date: Sat, 18 Jan 2014 20:05:47 GMT
	{
	"regions": [
	{
	"name": "customers",
	"type": "REPLICATE",
	"key-constraint": "java.lang.String",
	"value-constraint": "org.apache.geode.pdx.PdxInstance"
	},
	{
	"name": "items",
	"type": "REPLICATE",
	"key-constraint": null,
	"value-constraint": null
	},
	{
	"name": "orders",
	"type": "PARTITION",
	"key-constraint": null,
	"value-constraint": null
	},
	{
	"name": "primitiveKVStore",
	"type": "PARTITION",
	"key-constraint": null,
	"value-constraint": null
	},
	{
	"name": "empty_region",
	"type": "EMPTY",
	"key-constraint": "java.lang.String",
	"value-constraint": "org.apache.geode.pdx.PdxInstance"
	}
	]
	}
	```

	Each region listed in the response includes the following region attributes:

	- name. Name of the region.
	- type. Type of region. For example, REPLICATE, PARTITION, or EMPTY. See [Region Types](../developing/region_options/region_types.html#region_types) for more information.
	- key-constraint. If defined, the fully qualified class name of the key's type. Otherwise, null.
	- value-constraint. If defined, the fully qualified class name of the value's type. Otherwise, null.

	If no resources (regions) are available in the cluster, the call returns a 404 NOT FOUND error.

	## Reading Region Data

	You can read data from a region by using any of the following REST-enabled mechanisms:

	- GET /geode/v1/{region}?limit=ALL - Read all entries in a region
	- *GET /geode/v1/{region}?limit=N*** - Read a limited number of entries in a region
	- GET /geode/v1/{region}/keys - List all keys in a region
	- GET /geode/v1/{region}/{keys} - Read data for specific key or keys in a region

	Reading Entries

	To read entries in a region, use the following REST endpoint:

	``` pre
	GET /geode/v1/{region}?[limit={<number>\|ALL}]
	```

	For example:

	``` pre
	http://localhost:7070/geode/v1/items
	```

	To read all entries in the region, specify instead:

	``` pre
	http://localhost:7070/geode/v1/items?limit=ALL
	```

	To read 80 entries from the region, specify:

	``` pre
	http://localhost:7070/geode/v1/items?limit=80
	```

	Setting the limit parameter is optional. If you do not specify a limit, the request will return 50 results by default. The returned order of the results is not guaranteed; however, the response values (JSON) are specified in the same order as the list of comma-separated keys returned in the "Content-location" header.

	Reading Keys

	To list all keys in a region, use the following endpoint:

	``` pre
	/geode/v1/{region}/keys
	```

	For example:

	``` pre
	http://localhost:7070/geode/v1/items/keys
	```

	You can use the returned key to perform additional operations on the keys such as read, update or delete their values.

	Reading Entries By Key

	To obtain data for a specific key or set of keys, use the following endpoints:

	``` pre
	GET /geode/v1/{region}/{key1}
	```

	or

	``` pre
	GET /geode/v1/{region}/{key1},{key2},...,{keyN}
	```

	where you specify keys in a comma-delimited list.

	For example:

	``` pre
	http://localhost:7070/geode/v1/items/1

	http://localhost:7070/geode/v1/items/1,3,5
	```

	If one or more of the keys you provide in the list of keys is missing from the region, you will receive a 400 BAD STATUS error response.

	If you are providing multiple keys, you can also use the `ignoreMissingKey=true` parameter to prevent 400 errors. Any non-existing keys will instead return a null response. For example:

	``` pre
	http://localhost:7070/geode/v1/items/1,3,5?ignoreMissingKey=true
	```

	## Adding or Modifying Region Data

	To add data to a region, you have several options:

	- Create new a brand new entry (both key and value) in a region
	- Update or insert a value for a key (if the key does not exist, it will be created)
	- Update (replace) data for a key if and only if the key already exists in region
	- Compare existing value for a key before replacing value
	- Update or insert multiple values in the region for a set of provided keys

	Adding entries

	To add a new key and value to a region, you can use the following endpoint:

	``` pre
	POST /geode/v1/{region}?key=<key>
	```

	This endpoint only puts the entry into the region if the specified key does not already exist. If the key already exists, the request will fail with a 409 CONFLICT error.

	Note:
	If you do not specify a key for this request, a String representation of a numerical key will be generated automatically for you.

	Specify the value for the new entry in the request body. For example:

	``` pre
	http://localhost:7070/geode/v1/orders?key=2
	```

	``` pre
	Request Payload: application/json
	POST /geode/v1/orders?key=2

	Accept: application/json
	Content-Type: application/json
	{
	"@type": "org.apache.geode.web.rest.domain.Order",
	"purchaseOrderNo": 112,
	"customerId": 1012,
	"description": "Purchase Order for myCompany",
	"orderDate": "02/10/2014",
	"deliveryDate": "02/20/2014",
	"contact": "John Doe",
	"email": "John.Doe@example.com",
	"phone": "01-2048096",
	"totalPrice": 225,
	"items": [
	{
	"itemNo": 1,
	"description": "Product2, PartA",
	"quantity": 10,
	"unitPrice": 5,
	"totalPrice": 50
	},
	{
	"itemNo": 2,
	"description": "Product2, PartB",
	"quantity": 20,
	"unitPrice": 20,
	"totalPrice": 400
	}
	]
	}
	```

	Note that in the example above, `@type` is used to declare the value-constraint for the new entry. This declaration is required to provide interoperability between Java cache clients and REST clients.

	Alternately, you can also use the following endpoint to create a new entry:

	``` pre
	PUT /gemfire/v1/{region}/{key}
	```

	This endpoint will add the entry if the key does not exist. If the key already exists, the operation will update the entry.

	``` pre
	http://localhost:7070/geode/v1/orders/2
	```

	``` pre
	Request Payload: application/json
	PUT /geode/v1/orders/2
	Request Payload: application/json
	Content-Type: application/json
	Accept: application/json
	{
	"@type": "org.apache.geode.web.rest.domain.Order",
	"purchaseOrderNo": 1121,
	"customerId": 1012,
	"description": "Order for XYZ Corp",
	"orderDate": "02/10/2014",
	"deliveryDate": "02/20/2014",
	"contact": "Pie Doe",
	"email": "pie.doe@example.com",
	"phone": "01-2048096",
	"totalPrice": 225,
	"items": [
	{
	"itemNo": 1,
	"description": "Product-100",
	"quantity": 10,
	"unitPrice": 5,
	"totalPrice": 50
	}
	]
	}
	```

	Modifying existing entries

	<%=vars.product_name%> provides three different options for this type of operation. To update a value for the key, you can use:

	``` pre
	PUT /gemfire/v1/{region}/{key}
	PUT /gemfire/v1{region}/{key}?op=REPLACE
	PUT /gemfire/v1{region}/{key}?op=CAS
	```

	If you do not specify a parameter to the PUT operation, the request which will add or update the entry regardless of whether the key already exists in the region. See the example above.

	``` pre
	http://localhost:7070/geode/v1/orders/2
	```

	If you specify the op=REPLACE parameter, the request which will explicitly perform a Cache replace operation and will verify that the key exists before replacing the value. If the key does not exist in the specified region, you will receive a 404 NOT FOUND error. This operation is idempotent, meaning multiple identical requests will have the same effect as the initial request.

	``` pre
	http://localhost:7070/geode/v1/orders/2?op=REPLACE
	```

	If you specify the op=CAS parameter, the value will only be replaced with the `@new` value only if the specified `@old` value matches the current value of the key in the region. If the `@old` value does not match the current value, then a 409 CONFLICT error is thrown. If you receive a 409 CONFLICT error, you can call the `GET /geode/v1/{region}/{key}` endpoint to get an updated copy of the value. This operation is not idempotent and multiple identical requests will not have the same effect as the initial request. You can use this type of REST call to achieve a similar effect as optimistic locking.

	``` pre
	http://localhost:7070/geode/v1/orders/2?op=REPLACE
	```

	``` pre
	Request Payload: application/json

	PUT /geode/v1/orders/2?op=CAS

	Accept: application/json
	Content-Type: application/json
	{
	"@old": {
	"@type": "org.apache.geode.web.rest.domain.Order",
	"purchaseOrderNo": 1121,
	"customerId": 1012,
	"description": "Order for XYZ Corp",
	"orderDate": "02/10/2014",
	"deliveryDate": "02/20/2014",
	"contact": "Jelly Bean",
	"email": "jelly.bean@example.com",
	"phone": "01-2048096",
	"items": [
	{
	"itemNo": 1,
	"description": "Product-100",
	"quantity": 12,
	"unitPrice": 5,
	"totalPrice": 60
	}
	],
	"totalPrice": 225
	},
	"@new ": {
	"@type": "org.apache.geode.web.rest.domain.Order",
	"purchaseOrderNo": 1121,
	"customerId": 1013,
	"description": "Order for New Corp",
	"orderDate": "02/10/2014",
	"deliveryDate": "02/25/2014",
	"contact": "Vanilla Bean",
	"email": "vanillabean@example.com",
	"phone": "01-2048096",
	"items": [
	{
	"itemNo": 12345,
	"description": "part 123",
	"quantity": 12,
	"unitPrice": 29.99,
	"totalPrice": 149.95
	}
	],
	"totalPrice": 149.95
	}
	}
	```

	Adding or updating multiple values for a set of keys

	To update multiple values for keys, use:

	``` pre
	PUT /geode/v1/{region}/{key1},{key2},...,{keyN}
	```

	This REST call will update any keys that already exist and insert values for any keys that do not exist in the region.

	## Deleting Region Data

	There are three options for deleting data in a region using REST APIs:

	- Delete all the data in the region. Limited to replicated regions only; not available for partitioned regions.
	- Delete the data associated with a particular key
	- Delete the data associated with a set of keys

	Deleting all data

	To delete all data in the region, use the following endpoint:

	``` pre
	DELETE /geode/v1/{region}
	```

	For example:

	``` pre
	http://localhost:7070/geode/v1/items
	```

	Note that this does not delete the region itself, but instead all the entries in the region.

	Deleting data based on key

	Use:

	``` pre
	DELETE /geode/v1/{region}/{key}
	```

	or

	``` pre
	DELETE /geode/v1/{region}/{key}{key1},{key2},...{keyN}
	```

	If any of the supplied keys are not found in the region, the request will fail and return a 404 NOT FOUND ERROR.

	## <a id="topic_fcn_g25_m4" class="no-quick-link"></a>Working with Queries

	<%=vars.product_name%> supports the use of queries to extract data from its regions. Using REST APIs, you can create and execute either prepared or ad-hoc queries on <%=vars.product_name%> regions. You can also update and delete prepared queries.

	## Listing Queries

	To find out which predefined and named queries are available in your deployment, use the following endpoint:

	``` pre
	GET /geode/v1/queries
	```

	All queries that have been predefined and assigned IDs in <%=vars.product_name%> are listed.

	## <a id="topic_fcn_g25_m4__section_t4h_wtp_y4" class="no-quick-link"></a>Creating a New Query

	To create a query, use the following endpoint:

	``` pre
	POST /geode/v1/queries?id=<queryId>&q=<OQL-statement>
	```

	Here are some examples:

	``` pre
	http://localhost:7070/geode/v1/queries?id=selectOffers&q="SELECT DISTINCT c FROM /customers c, /orders o WHERE o.totalprice < $1 AND c.customerId = o.customerId"
	```

	Note:
	The query must be provided as a URL parameter. You cannot specify OQL in the request body at this time.

	You can specify query bind parameters ($1) in your predefined queries and then pass in values at runtime.

	To update this query at a later time, use the [PUT operation](#topic_fcn_g25_m4__section_oj1_b5p_y4) described below.

	## <a id="topic_fcn_g25_m4__section_b1p_wtp_y4" class="no-quick-link"></a>Executing a Prepared Query

	To run a prepared query, use:

	``` pre
	POST /geode/v1/queries/{queryId}
	```

	Specify the queryId in the URL. All query argument must be passed in the request body. For example:

	``` pre
	http://localhost:7070/geode/v1/queries/selectOrders
	```

	``` pre
	Request Payload: OQL bind parameter values HTTP message body of media type application/json
	POST /geode/v1/queries/selectOrders
	Accept: application/json
	Content-Type: application/json

	[
	{
	"@type": "int",
	"@value": 2
	},
	{
	"@type": "double",
	"@value": 110.00
	}
	]

	Response Payload: application/json

	200 OK
	Content-Length: <#-of-bytes>
	Content-Type: application/json

	[
	{
	"description": "Purchase order for company - B",
	"totalPrice": 350,
	"purchaseOrderNo": 1112,
	"customerId": 102,
	"deliveryDate": "Thu Feb 20 00:00:00 IST 2014",
	"contact": "John Doe",
	"email": "jDoe@example.com",
	"phone": "01-2048096",
	"items": [
	{
	"description": "Product-AAAA",
	"quantity": 10,
	"itemNo": 1,
	"unitPrice": 20,
	"totalPrice": 200,
	"type-class": "org.apache.geode.web.rest.domain.Item"
	},
	{
	"description": "Product-BBB",
	"quantity": 15,
	"itemNo": 2,
	"unitPrice": 10,
	"totalPrice": 150,
	"type-class": "org.apache.geode.web.rest.domain.Item"
	}
	],
	"orderDate": "Mon Feb 10 00:00:00 IST 2014",
	"type-class": "org.apache.geode.web.rest.domain.Order"
	},
	{...},
	{...}
	}
	```

	Another example:

	``` pre
	http://localhost:7070/geode/v1/queries/selectOrders
	```

	``` pre
	Request Payload: OQL bind parameter values HTTP message body of media type application/json
	POST /geode/v1/queries/selectCustomer
	Accept: application/json
	Content-Type: application/json
	{
	"args": [
	{
	"@type": "int",
	"@value": 101
	}
	]
	}

	Response-Payload: application/json

	200 Ok
	Content-Length: 140
	Content-Type: application/json
	[
	{
	"firstName": "Jane",
	"lastName": "Doe",
	"customerId": 101,
	"type-class": "org.apache.geode.web.rest.domain.Customer"
	}
	]
	```

	## <a id="topic_fcn_g25_m4__section_oj1_b5p_y4" class="no-quick-link"></a>Modifying a Prepared Query

	To modify an existing prepared query, use the following endpoint:

	``` pre
	PUT /geode/v1/queries/{queryId}
	```

	Here are some examples:

	``` pre
	http://localhost:7070/geode/v1/queries/selectOffers&q="SELECT DISTINCT c FROM /customers c, /orders o WHERE o.totalprice < $1 AND c.customerId = o.customerId"
	```

	You can specify query bind parameters ($1) in your predefined queries, and then pass in values at runtime.

	A PUT operation will only succeed if the specified queryId already exists (for example, created with the [POST operation](#topic_fcn_g25_m4__section_t4h_wtp_y4) above.) If the queryId does already exist, you will receive a 404 response - "Named query (selectKey456) does not exist!"

	## <a id="topic_fcn_g25_m4__section_igg_b5p_y4" class="no-quick-link"></a>Deleting a Prepared Query

	To delete an existing prepared query, use the following endpoint:

	``` pre
	DELETE /geode/v1/queries/{queryId}
	```

	## <a id="topic_fcn_g25_m4__section_wbk_b5p_y4" class="no-quick-link"></a>Executing an Ad-Hoc Query

	To run an unnamed query, use the following endpoint:

	``` pre
	GET /geode/v1/queries/adhoc?q=<OQL-statement>
	```

	Provide the OQL query string directly in the URL enclosed in single quotes.

	For example:

	``` pre
	http://localhost:7070/geode/v1/queries/adhoc?q="SELECT * FROM /customers"
	```

	## <a id="topic_rbc_h25_m4" class="no-quick-link"></a>Working with Functions

	<%=vars.product_name%> REST APIs support the discovery and execution of predefined <%=vars.product_name%> functions on your cluster deployments.

	Before you can access functions using REST APIs, you must have already defined and registered the functions in your <%=vars.product_name%> deployment. Additionally, any domain objects that are being accessed by the functions must be available on the CLASSPATH of the server running the REST endpoint service.

	You can do the following with functions:

	- List all functions available in the <%=vars.product_name%> cluster.
	- Execute a function, optionally specifying the region and members and/or member groups that are targeted by the function

	## Listing Functions

	To list all functions that are currently registered and deployed in the <%=vars.product_name%> cluster, use the following endpoint:

	``` pre
	GET /geode/v1/functions
	```

	The list of returned functions includes the functionId, which you can use to execute the function as described in the next section.

	## Executing Functions

	To execute a function on a <%=vars.product_name%> cluster, use the following endpoint:

	``` pre
	POST /geode/v1/functions/{functionId}?[&onRegion=regionname\|&onMembers=member1,member2,...,memberN\|&onGroups=group1,group2,...,groupN]
	```

	You have the option to target a specific region and members or member groups when executing your function. If you do not specify these parameters, the function will execute on all members that are hosting data in the entire cluster by default. Function arguments are passed in the request body.

	For example:

	``` pre
	http://localhost:7070/geode/v1/functions/AddFreeItemToOrders
	```

	``` pre
	Request Payload: application/json
	POST /geode/v1/functions/AddFreeItemToOrders
	Accept: application/json
	Content-Type: application/json

	[
	{
	"@type": "double",
	"@value": 210
	},
	{
	"@type": "org.apache.geode.web.rest.domain.Item",
	"itemNo": "599",
	"description": "Part X Free on Bumper Offer",
	"quantity": "2",
	"unitprice": "5",
	"totalprice": "10.00"
	}
	]
	```

	In the above example, the `Item` domain object must be in the CLASSPATH of all members receiving the function. If the object is not defined, the function will fail with an `Internal Server` error. Look for `ClassNotFoundException`s in the stack trace.