Region Management
Create Region
API | Sample Request Body | Status Code | Response Body |
---|---|---|---|
Endpoint: http://locator:7070/management/experimental/regions Method: POST Headers: Authorization Permission Required: DATA:MANAGE Body: Types supported by this Rest API is defined in RegionType: Request Body public enum RegionType { PARTITION, PARTITION_REDUNDANT, PARTITION_PERSISTENT, PARTITION_REDUNDANT_PERSISTENT, PARTITION_OVERFLOW, PARTITION_REDUNDANT_OVERFLOW, PARTITION_PERSISTENT_OVERFLOW, PARTITION_REDUNDANT_PERSISTENT_OVERFLOW, PARTITION_HEAP_LRU, PARTITION_REDUNDANT_HEAP_LRU, PARTITION_PROXY, PARTITION_PROXY_REDUNDANT, REPLICATE, REPLICATE_PERSISTENT, REPLICATE_OVERFLOW, REPLICATE_PERSISTENT_OVERFLOW, REPLICATE_HEAP_LRU, REPLICATE_PROXY } | Sample Request { "name": "regionA", "type": "REPLICATE" } | 200 | Success Response { "memberStatuses": [{ "memberName": "server-2", "success": true, "message": "Region successfully created." }, { "memberName": "server-3", "success": true, "message": "Region successfully created." }], "statusCode": "OK", "statusMessage": "Successfully updated config for group2", "uri": "/management/experimental/regions/disJoint", "result": [] } |
409 | Name conflict { "memberStatuses" : { }, "statusCode" : "ENTITY_EXISTS", "statusMessage" : "cache element Foo already exists.", "successful" : false } | ||
400 | Error Response - missing required parameter { "memberStatuses" : { }, "statusCode" : "ILLEGAL_ARGUMENT", "statusMessage" : "Name of the region has to be specified.", "successful" : false } Error Response - invalid parameter { "memberStatuses" : { }, "statusCode" : "ILLEGAL_ARGUMENT", "statusMessage" : "Region names may not begin with a double-underscore: __Foo__", "successful" : false } | ||
401 | Error Response - unauthenticated { "memberStatuses" : { }, "statusCode" : "UNAUTHENTICATED", "statusMessage" : "Authentication error. Please check your credentials", "successful" : false } | ||
403 | Error Response - not authorized { "memberStatuses" : { }, "statusCode" : "UNAUTHORIZED", "statusMessage" : "user not authorized for DATA:MANAGE", "successful" : false } | ||
500 | Error Response { "memberStatuses" : { }, "statusCode" : "ERROR", "statusMessage" : "cluster persistence service is not running", "successful" : false } |
Notes:
- the CREATE[POST] endpoint is not idempotent, you will receive a 409 when creating the a region with the same name the 2nd time.
- if group name is "cluster" or omitted, the region will be created on all the data members in this cluster.
401 and 403 responses are omitted for the rest of the end points.
List Regions
API | Status Code | Response Body |
---|---|---|
200 | Success Response { "statusCode": "OK", "result": [{ "config": { "class": "org.apache.geode.cache.configuration.RegionConfig", "groups": ["group2"], "regionAttributes": { "dataPolicy": "PARTITION", "concurrencyChecksEnabled": true }, "name": "customers2", "type": "PARTITION", "uri": "/management/experimental/regions/customers2" }, "runtimeInfo": [{ "class": "org.apache.geode.management.runtime.RuntimeRegionInfo", "entryCount": 0 }] }, { "config": { "class": "org.apache.geode.cache.configuration.RegionConfig", "groups": ["group2", "group1"], "regionAttributes": { "dataPolicy": "PARTITION", "concurrencyChecksEnabled": true }, "name": "customers3", "type": "PARTITION", "uri": "/management/experimental/regions/customers3" }, "runtimeInfo": [{ "class": "org.apache.geode.management.runtime.RuntimeRegionInfo", "entryCount": 0 }] }] } | |
401 | Error Response { "message": "Missing authentication credential header(s)" } | |
403 | Error Response { "message": "User1 not authorized for CLUSTER:READ" } |
Get Region
API | Status Code | Response Body |
---|---|---|
200 | Success Response { "statusCode": "OK", "result": [{ "config": { "class": "org.apache.geode.cache.configuration.RegionConfig", "groups": ["group2"], "regionAttributes": { "dataPolicy": "PARTITION", "concurrencyChecksEnabled": true }, "name": "Foo", "type": "PARTITION", "uri": "/management/experimental/regions/Foo" }, "runtimeInfo": [{ "class": "org.apache.geode.management.runtime.RuntimeRegionInfo", "entryCount": 0 }] }] } | |
401 | Error Response { "message": "Missing authentication credential header(s)" } | |
403 | Error Response { "message": "User1 not authorized for CLUSTER:READ" } | |
404 | Error Response { "message": "Region with name '/Foo' does not exist" } |
Delete Region
API | Status Code | Response Body |
---|---|---|
Endpoint: http://locator:7070/management/experimental/regions/Foo Method: DELETE Headers: Authorization | 204 | Error Response { "memberStatuses": [{ "memberName": "server-1", "success": true, "message": "Region successfully deleted." }, { "memberName": "server-3", "success": true, "message": "Region successfully deleted." }], "statusCode": "OK", "statusMessage": "Successfully removed config for [group1]", "result": [] } |
304 | Error Response { "message": "Region with name '/Foo' does not exist" } | |
401 | Error Response { "message": "Missing authentication credential header(s)" } | |
403 | Error Response { "message": "User1 not authorized for DATA:MANAGE" } | |
500 | Error Response { "message": "Failed to delete region /Foo because of <reason>" } |
Note that the DELETE endpoint is idempotent – i.e. it should be a NOOP if the region does not exist.
Member Management
List Members
API | Status Code | Response Body |
---|---|---|
Permission Required: CLUSTER:READ | 200 | Success Response { "statusCode": "OK", "result": [{ "config": { "class": "org.apache.geode.management.configuration.MemberConfig" }, "runtimeInfo": [{ "class": "org.apache.geode.management.runtime.MemberInformation", "name": "locator-0", "id": "10.118.20.127(locator-0:4317:locator)<ec><v0>:41001", "workingDirPath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "logFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "statArchiveFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "locators": "10.118.20.127[64759]", "heapUsage": 209, "maxHeapSize": 480, "initHeapSize": 512, "cacheXmlFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "host": "10.118.20.127", "processId": 4317, "locatorPort": 64759, "httpServicePort": 22500, "httpServiceBindAddress": "localhost", "clientCount": 0, "cpuUsage": 0.0, "webSSL": false, "coordinator": true, "secured": false, "server": false }, { "class": "org.apache.geode.management.runtime.MemberInformation", "name": "server-1", "id": "10.118.20.127(server-1:4318)<v1>:41002", "workingDirPath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm1", "logFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm1", "statArchiveFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm1", "locators": "localhost[64759]", "heapUsage": 107, "maxHeapSize": 491, "initHeapSize": 512, "cacheXmlFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm1/cache.xml", "host": "10.118.20.127", "processId": 4318, "locatorPort": 0, "httpServicePort": 0, "clientCount": 0, "cpuUsage": 0.0, "webSSL": false, "coordinator": false, "secured": false, "server": true, "cacheServerInfo": [{ "port": 64772, "maxConnections": 800, "maxThreads": 0, "running": true }] }] }] } |
Endpoint: http://locator:7070/management/experimental/members?id=server-1 Method: GET Headers: Authorization Permission Required: CLUSTER:READ | 200 | Success Response { "statusCode": "OK", "result": [{ "config": { "class": "org.apache.geode.management.configuration.MemberConfig" }, "runtimeInfo": [{ "class": "org.apache.geode.management.runtime.MemberInformation", "name": "locator-0", "id": "10.118.20.127(locator-0:4317:locator)<ec><v0>:41001", "workingDirPath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "logFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "statArchiveFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "locators": "10.118.20.127[64759]", "heapUsage": 209, "maxHeapSize": 480, "initHeapSize": 512, "cacheXmlFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "host": "10.118.20.127", "processId": 4317, "locatorPort": 64759, "httpServicePort": 22500, "httpServiceBindAddress": "localhost", "clientCount": 0, "cpuUsage": 0.0, "webSSL": false, "coordinator": true, "secured": false, "server": false }] }] } |
Endpoint: http://locator:7070/management/experimental/members?id=Non-Existent Method: GET Headers: Authorization Permission Required: CLUSTER:READ | 200 | Success Response { "memberStatuses": {}, "statusCode": "OK", "statusMessage": null, "result": [] } |
Get Member
API | Status Code | Response Body |
---|---|---|
Endpoint: http://locator:7070/management/experimental/members/server-1 Method: GET Headers: Authorization Permission Required: CLUSTER:READ | 200 | Success Response { "statusCode": "OK", "result": [{ "config": { "class": "org.apache.geode.management.configuration.MemberConfig" }, "runtimeInfo": [{ "class": "org.apache.geode.management.runtime.MemberInformation", "name": "locator-0", "id": "10.118.20.127(locator-0:4317:locator)<ec><v0>:41001", "workingDirPath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "logFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "statArchiveFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "locators": "10.118.20.127[64759]", "heapUsage": 209, "maxHeapSize": 480, "initHeapSize": 512, "cacheXmlFilePath": "/Users/jiliao/projects/geode/geode-assembly/dunit/vm0", "host": "10.118.20.127", "processId": 4317, "locatorPort": 64759, "httpServicePort": 22500, "httpServiceBindAddress": "localhost", "clientCount": 0, "cpuUsage": 0.0, "webSSL": false, "coordinator": true, "secured": false, "server": false }] }] } |
Endpoint: http://locator:7070/management/experimental/members/Non-Existent Method: GET Headers: Authorization Permission Required: CLUSTER:READ | 404 | Error Response { "memberStatuses": {}, "statusCode": "ENTITY_NOT_FOUND", "statusMessage": "Unable to find the member with id = Non-Existent", "result": [] } |
Index Management
List Indexes
API | Status Code | Response Body |
---|---|---|
Endpoint: http://locator:7070/management/experimental/regions/{regionName}/indexes Method: GET Headers: Authorization Permission Required: CLUSTER:READ | 200 | Success Response { "statusCode": "OK", "result": [{ "config": { "class": "org.apache.geode.cache.configuration.RegionConfig$Index", "name": "index1", "expression": "id", "fromClause": "/region1", "keyIndex": true, "type": "key", "regionName": "region1", "uri": "/management/experimental/regions/region1/indexes/index1" } }, { "config": { "class": "org.apache.geode.cache.configuration.RegionConfig$Index", "name": "index2", "expression": "key", "fromClause": "/region1", "keyIndex": true, "type": "key", "regionName": "region1", "uri": "/management/experimental/regions/region1/indexes/index2" } }] } |
Get Index
API | Status Code | Response Body |
---|---|---|
Endpoint: http://locator:7070/management/experimental/regions/{regionName}/indexes/{indexName} Method: GET Headers: Authorization Permission Required: CLUSTER:READ | 200 | Success Response { "statusCode": "OK", "result": [{ "config": { "class": "org.apache.geode.cache.configuration.RegionConfig$Index", "name": "index1", "expression": "id", "fromClause": "/region1", "keyIndex": true, "type": "key", "regionName": "region1", "uri": "/management/experimental/regions/region1/indexes/index1" } }] } |
PDX Management
Configure PDX
API | Request Body | Status Code | Response Body |
---|---|---|---|
Endpoint:http://locator:7070/management/experimental/configurations/pdx Method: POST Headers: Authorization Permission Required: CLUSTER:MANAGE | Sample Request {"readSerialized":true} | 200 | Success Response { "memberStatuses": [{ "memberName": "server-1", "success": true, "message": "Server needs to be restarted for this configuration change to be realized." }], "statusCode": "OK", "statusMessage": "Successfully updated config for cluster", "uri": "/management/experimental/configurations/pdx", "result": [] } |
Gateway Management
List Gateway Receivers
API | Status Code | Response Body |
---|---|---|
Endpoint: http://locator:7070/management/experimental/gateways/receivers Method: GET Headers: Authorization Permission Required: CLUSTER:READ | 200 | Success Response { "statusCode": "OK", "result": [{ "config": { "class": "org.apache.geode.cache.configuration.GatewayReceiverConfig", "groups": ["group2"], "startPort": "5002", "endPort": "5500", "uri": "/management/experimental/gateways/receivers/group2" } }, { "config": { "class": "org.apache.geode.cache.configuration.GatewayReceiverConfig", "groups": ["group1"], "startPort": "5000", "endPort": "5500", "uri": "/management/experimental/gateways/receivers/group1" }, "runtimeInfo": [{ "class": "org.apache.geode.management.runtime.GatewayReceiverInfo", "memberName": "server-1", "running": true, "port": 5134 }] }] } |
Create Gateway Receiver
API | Status Code | Request Body | Response Body |
---|---|---|---|
Endpoint: http://locator:7070/management/experimental/gateways/receivers Method: POST Headers: Authorization Permission Required: CLUSTER:MANAGE | 201 | Sample Request { "startPort":"5000", "group":"group1" } | Success Response { "memberStatuses": [{ "memberName": "server-1", "success": true, "message": "success" }], "statusCode": "OK", "statusMessage": "Successfully updated config for group1", "uri": "/management/experimental/gateways/receivers/group1", "result": [] } |
Rebalance Operation
Start Rebalance
API | Status Code | Request Body | Response Body |
---|---|---|---|
Endpoint: http://locator:7070/management/experimental/operations/rebalance Method: POST Headers: Authorization Permission Required: DATA:MANAGE | 202 | Sample Request { "excludeRegions": [], "includeRegions": [], "simulate": false } | Success Response { "statusCode": "ACCEPTED", "statusMessage": "async operation started (GET uri to check status)", "uri": "/management/experimental/operations/rebalance/8a70d6c4", "operationStart": "2019-07-25T10:17:42.004Z" } |
List Rebalance History
API | Status Code | Response Body |
---|---|---|
Endpoint: http://locator:7070/management/experimental/operations/rebalance Method: GET Headers: Authorization Permission Required: DATA:MANAGE | 200 | Success Response { "statusCode": "OK", "result": [ { "statusCode": "OK", "statusMessage": "finished successfully", "uri": "/management/experimental/operations/rebalance/8a70d6c4", "operationStart": "2019-07-25T10:17:42.004Z", "operationEnded": "2019-07-25T10:17:42.060Z" }, { "statusCode": "IN_PROGRESS", "statusMessage": "in progress", "uri": "/management/experimental/operations/rebalance/a7d6204c", "operationStart": "2019-07-26T04:57:22.534Z", } ] } |
Get Rebalance Status
API | Status Code | Response Body |
---|---|---|
Endpoint: http://locator:7070/management/experimental/operations/rebalance/{id} Method: GET Headers: Authorization Permission Required: DATA:MANAGE | 200 | Success Response { "statusCode": "OK", "statusMessage": "finished successfully", "operationStart": "2019-07-25T10:17:42.004Z", "operationEnded": "2019-07-25T10:17:42.060Z", "result": { "rebalanceRegionResults": [ { "regionName": "testRegion2", "bucketCreateBytes": 0, "bucketCreateTimeInMilliseconds": 0, "bucketCreatesCompleted": 0, "bucketTransferBytes": 0, "bucketTransferTimeInMilliseconds": 0, "bucketTransfersCompleted": 0, "primaryTransferTimeInMilliseconds": 0, "primaryTransfersCompleted": 0, "timeInMilliseconds": 17 }, { "regionName": "testRegion1", "bucketCreateBytes": 0, "bucketCreateTimeInMilliseconds": 0, "bucketCreatesCompleted": 0, "bucketTransferBytes": 0, "bucketTransferTimeInMilliseconds": 0, "bucketTransfersCompleted": 0, "primaryTransferTimeInMilliseconds": 0, "primaryTransfersCompleted": 0, "timeInMilliseconds": 5 } ] } } |
404 | Success Response { "statusCode": "ENTITY_NOT_FOUND", "statusMessage": "Operation id = 12345678 not found" } | |
500 | Success Response { "statusCode": "ERROR", "statusMessage": "rebalance returned info: Distributed system has no regions that can be rebalanced" } |