You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

Region Management

Create Region 

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/regions

Method: POST

Headers: Authorization

Permission Required: DATA:MANAGE


Sample Request
{
	"name": "regionA",
	"type": "REPLICATE"
}

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
}
201
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 configuration for cluster.",
	"uri": "/management/experimental/regions/regionA"
}
409
Name conflict
{
   "statusMessage" : "Region 'regionA' already exists on member(s) server-2.",
   "statusCode" : "ENTITY_EXISTS"
}
400
Error Response - empty required parameter
{
  "statusCode" : "ILLEGAL_ARGUMENT",
  "statusMessage" : "Region identifier is required.",
}
Error Response - invalid parameter
{
  "statusCode" : "ILLEGAL_ARGUMENT",
  "statusMessage" : "Region names may not begin with a double-underscore: __Foo.",
}

Given an unknown input attribute, for example: foobar in: 

curl -d '{"name":"replicate2","type":"REPLICATE","foobar":"value"}' -H 'Content-Type: application/json' http://localhost:7070/management/experimental/regions

the output is:

{

   "statusCode" : "ILLEGAL_ARGUMENT",

   "statusMessage" : "JSON parse error: Unrecognized field \"foobar\" (class org.apache.geode.cache.configuration.Region), not marked as ignorable; nested exception is com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field \"foobar\" (class org.apache.geode.cache.configuration.Region), not marked as ignorable (9 known properties: \"indexes\", \"groups\", \"type\", \"regionAttributes\", \"customRegionElements\", \"regions\", \"entries\", \"name\", \"group\"])\n at [Source: (PushbackInputStream); line: 1, column: 59] (through reference chain: org.apache.geode.cache.configuration.Region[\"foobar\"])"

}


401
Error Response - unauthenticated
{
  "statusCode" : "UNAUTHENTICATED",
  "statusMessage" : "Authentication error. Please check your credentials.",
}
403
Error Response - not authorized
{
  "statusCode" : "UNAUTHORIZED",
  "statusMessage" : "User not authorized for DATA:MANAGE.",
}
500
Error Response
{
  "statusCode" : "ERROR",
  "statusMessage" : "Cluster configuration service is not running.",
}

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

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/regions

Method: GET

Headers: Authorization



200

Success Response
{
	"statusCode": "OK",
	"result": [{
		"config": {
			"groups": ["group2"],
			"regionAttributes": {
				"dataPolicy": "PARTITION",
				"concurrencyChecksEnabled": true
			},
			"name": "customers2",
			"type": "PARTITION",
			"uri": "/management/experimental/regions/customers2"
		},
		"runtimeInfo": [{
			"entryCount": 0
		}]
	}, {
		"config": {
			"groups": ["group2", "group1"],
			"regionAttributes": {
				"dataPolicy": "PARTITION",
				"concurrencyChecksEnabled": true
			},
			"name": "customers3",
			"type": "PARTITION",
			"uri": "/management/experimental/regions/customers3"
		},
		"runtimeInfo": [{
			"entryCount": 0
		}]
	}]
}
401
Error Response
{
  "statusCode" : "UNAUTHENTICATED",
  "statusMessage" : "Authentication error. Please check your credentials.",
}
403
Error Response
{
  "statusCode" : "UNAUTHORIZED",
  "statusMessage" : "User not authorized for DATA:MANAGE.",
}


Get Region

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/regions/Foo

Method: GET

Headers: Authorization



200

Success Response
{
	"statusCode": "OK",
	"result": {
		"config": {
			"groups": ["group2"],
			"regionAttributes": {
				"dataPolicy": "PARTITION",
				"concurrencyChecksEnabled": true
			},
			"name": "Foo",
			"type": "PARTITION",
			"uri": "/management/experimental/regions/Foo"
		},
		"runtimeInfo": [{
			"entryCount": 0
		}]
	}
}
401
Error Response
{
  "statusCode" : "UNAUTHENTICATED",
  "statusMessage" : "Authentication error. Please check your credentials.",
}
403
Error Response
{
  "statusCode" : "UNAUTHORIZED",
  "statusMessage" : "User not authorized for DATA:MANAGE.",
}
404
Not Found Response
{
     "statusCode": "ENTITY_NOT_FOUND",
     "statusMessage": "Region 'Foo' does not exist."
}

Delete Region

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/regions/Foo

Method: DELETE

Headers: Authorization



200

Success 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 configuration for [cluster]."
}
404
Not Found Response
{
     "statusCode":"ENTITY_NOT_FOUND",
     "statusMessage":"Region 'Foo' does not exist."
}
401
Error Response
{
  "statusCode" : "UNAUTHENTICATED",
  "statusMessage" : "Authentication error. Please check your credentials.",
}
403
Error Response
{
  "statusCode" : "UNAUTHORIZED",
  "statusMessage" : "User not authorized for DATA:MANAGE.",
}
500
Error Response
{
    "statusCode" : "ERROR",
    "statusMessage": "Failed to delete on all members."
}

Note that the DELETE endpoint is idempotent – i.e. it should be a NOOP if the region does not exist.


Member Management

List Members

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/members

Method: GET

Headers: Authorization

Permission Required: CLUSTER:READ

200
Success Response
{
	"statusCode": "OK",
	"result": [{
		"runtimeInfo": [{
			"memberName": "locator-0",
			"id": "10.10.10.10(locator-0:4317:locator)<ec><v0>:41001",
			"workingDirPath": "/Users/user/projects/geode/vm0",
			"logFilePath": "/Users/user/projects/geode/vm0",
			"statArchiveFilePath": "/Users/user/projects/geode/vm0",
			"locators": "10.10.10.10[64759]",
			"heapUsage": 209,
			"maxHeapSize": 480,
			"initHeapSize": 512,
			"cacheXmlFilePath": "/Users/user/projects/geode/vm0",
			"host": "10.10.10.10",
			"processId": 4317,
			"locatorPort": 64759,
			"httpServicePort": 22500,
			"httpServiceBindAddress": "localhost",
			"clientCount": 0,
			"cpuUsage": 0.0,
			"webSSL": false,
			"coordinator": true,
			"secured": false,
			"server": false,
            "status": "online"
		}, {
			"memberName": "server-1",
			"id": "10.10.10.10(server-1:4318)<v1>:41002",
			"workingDirPath": "/Users/user/projects/geode/vm1",
			"logFilePath": "/Users/user/projects/geode/vm1",
			"statArchiveFilePath": "/Users/user/projects/geode/vm1",
			"locators": "localhost[64759]",
			"heapUsage": 107,
			"maxHeapSize": 491,
			"initHeapSize": 512,
			"cacheXmlFilePath": "/Users/user/projects/geode/vm1/cache.xml",
			"host": "10.10.10.10",
			"processId": 4318,
			"locatorPort": 0,
			"httpServicePort": 0,
			"clientCount": 0,
			"cpuUsage": 0.0,
			"webSSL": false,
			"coordinator": false,
			"secured": false,
			"server": true,
            "status": "online",
			"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" : {
            "id" : "locator-0",
            "uri" : "/management/experimental/members/locator-0",
        },
		"runtimeInfo": [{
			"memberName": "locator-0",
			"id": "10.10.10.10(locator-0:4317:locator)<ec><v0>:41001",
			"workingDirPath": "/Users/user/projects/geode/vm0",
			"logFilePath": "/Users/user/projects/geode/vm0",
			"statArchiveFilePath": "/Users/user/projects/geode/vm0",
			"locators": "10.10.10.10[64759]",
			"heapUsage": 209,
			"maxHeapSize": 480,
			"initHeapSize": 512,
			"cacheXmlFilePath": "/Users/juser/projects/geode/vm0",
			"host": "10.10.10.10",
			"processId": 4317,
			"locatorPort": 64759,
			"httpServicePort": 22500,
			"httpServiceBindAddress": "localhost",
			"clientCount": 0,
			"cpuUsage": 0.0,
			"webSSL": false,
			"coordinator": true,
			"secured": false,
			"server": false,
            "status": "online"
		}]
	}]
}

Endpoint: http://locator:7070/management/experimental/members?id=Non-Existent

Method: GET

Headers: Authorization

Permission Required: CLUSTER:READ

200
Success Response
{
   "statusCode" : "OK",
   "result" : [
      {
         "config" : {
            "uri" : "/management/experimental/members/Non-Existent",
            "id" : "Non-Existent"
         }
      }
   ]
}

Get Member

APIStatus CodeResponse 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" : {
            "id" : "server-1",
            "uri" : "/management/experimental/members/server-1",
        },
		"runtimeInfo": [{
			"memberName": "server-1",
			"id": "10.10.10.10(locator-0:4317:locator)<ec><v0>:41001",
			"workingDirPath": "/Users/user/projects/geode/vm0",
			"logFilePath": "/Users/user/projects/geode/vm0",
			"statArchiveFilePath": "/Users/user/projects/geode/vm0",
			"locators": "10.10.10.10[64759]",
			"heapUsage": 209,
			"maxHeapSize": 480,
			"initHeapSize": 512,
			"cacheXmlFilePath": "/Users/user/projects/geode/vm0",
			"host": "10.10.10.10",
			"processId": 4317,
			"locatorPort": 64759,
			"httpServicePort": 22500,
			"httpServiceBindAddress": "localhost",
			"clientCount": 0,
			"cpuUsage": 0.0,
			"webSSL": false,
			"coordinator": true,
			"secured": false,
			"server": false,
            "status": "online"
		}]
	}
}

Endpoint: http://locator:7070/management/experimental/members/Non-Existent

Method: GET

Headers: Authorization

Permission Required: CLUSTER:READ

404
Not Found Response
{
   "statusCode" : "ENTITY_NOT_FOUND",
   "statusMessage" : "Member 'Non-Existent' does not exist."
}

Index Management

List Indexes

APIStatus CodeResponse 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": {
			"name": "index1",
			"expression": "id",
			"fromClause": "/region1",
			"keyIndex": true,
			"type": "key",
			"regionName": "region1",
			"uri": "/management/experimental/regions/region1/indexes/index1"
		}
	}, {
		"config": {
			"name": "index2",
			"expression": "key",
			"fromClause": "/region1",
			"keyIndex": true,
			"type": "key",
			"regionName": "region1",
			"uri": "/management/experimental/regions/region1/indexes/index2"
		}
	}]
}

Get Index

APIStatus CodeResponse 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": {
			"name": "index1",
			"expression": "id",
			"fromClause": "/region1",
			"keyIndex": true,
			"type": "key",
			"regionName": "region1",
			"uri": "/management/experimental/regions/region1/indexes/index1"
		}
	}
}

Endpoint: http://locator:7070/management/experimental/regions/{regionName}/indexes/{indexName}

Method: GET

Headers: Authorization

Permission Required: CLUSTER:READ

404
Not found response
{
  "statusCode": "ENTITY_NOT_FOUND",
  "statusMessage": "Index 'foo' does not exist in region 'replicate'."
}

PDX Management

Configure PDX

APIStatus CodeResponse Body

Endpoint:http://locator:7070/management/experimental/configurations/pdx

Method: POST

Headers: Authorization

Permission Required: CLUSTER:MANAGE

Sample Request
{"readSerialized":true}
201
Success Response
{
  "statusCode": "OK",
  "statusMessage": "Successfully updated configuration for cluster.",
  "uri": "/management/experimental/configurations/pdx",
  "memberStatuses": [
    {
      "memberName": "server-1",
      "success": true,
      "message": "Server 'server-1' needs to be restarted for this configuration change to be realized."
    }
  ]
}

Gateway Management

Create Gateway Receiver

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/gateways/receivers

Method: POST

Headers: Authorization

Permission Required: CLUSTER:MANAGE

Sample Request
{
 "startPort":"5000",
 "group":"group1"
}
201
Success Response
{
  "statusCode": "OK",
  "statusMessage": "Successfully updated configuration for group1.",
  "uri": "/management/experimental/gateways/receivers/group1"
}

List Gateway Receivers

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/gateways/receivers

Method: GET

Headers: Authorization

Permission Required: CLUSTER:READ

200
Success Response
{
	"statusCode": "OK",
	"result": [{
		"config": {
			"groups": ["group2"],
			"startPort": "5002",
			"endPort": "5500",
			"uri": "/management/experimental/gateways/receivers/group2"
		}
	}, {
		"config": {
			"groups": ["group1"],
			"startPort": "5000",
			"endPort": "5500",
			"uri": "/management/experimental/gateways/receivers/group1"
		},
		"runtimeInfo": [{
			"memberName": "server-1",
			"running": true,
			"port": 5134
		}]
	}]
}

Get Gateway Receiver

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/gateways/receivers/{receiverGroup}

Method: GET

Headers: Authorization

Permission Required: CLUSTER:READ

200
Success Response
{
	"statusCode": "OK",
	"result": {
		"config": {
			"groups": ["group1"],
			"startPort": "5000",
			"endPort": "5500",
			"uri": "/management/experimental/gateways/receivers/group1"
		},
		"runtimeInfo": [{
			"memberName": "server-1",
			"running": true,
			"port": 5134
		}]
	}
}

Rebalance Operation

Start Rebalance

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/operations/rebalances

Method: POST

Headers: Authorization

Permission Required: DATA:MANAGE

Sample Request
{
"excludeRegions": [],
"includeRegions": [],
"simulate": false
}
202
Success Response
{
  "statusCode": "ACCEPTED",
  "statusMessage": "Operation started.  Use the URI to check its status.",
  "uri": "/management/experimental/operations/rebalances/8a70d6c4",
  "operationStart": "2019-07-25T10:17:42.004Z"
}

List Rebalance History

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/operations/rebalances

Method: GET

Headers: Authorization

Permission Required: DATA:MANAGE

200
Success Response
{
  "statusCode": "OK",
  "result": [
    {
      "statusCode": "OK",
      "statusMessage": "Operation finished successfully.",
      "uri": "/management/experimental/operations/rebalances/8a70d6c4",
      "operationStart": "2019-07-25T10:17:42.004Z",
      "operationEnded": "2019-07-25T10:17:42.060Z"
    },
    {
      "statusCode": "IN_PROGRESS",
      "statusMessage": "Operation in progress.",
      "uri": "/management/experimental/operations/rebalances/a7d6204c",
      "operationStart": "2019-07-26T04:57:22.534Z",
    }
  ]
}

Get Rebalance Status

APIStatus CodeResponse Body

Endpoint: http://locator:7070/management/experimental/operations/rebalances/{id}

Method: GET

Headers: Authorization

Permission Required: DATA:MANAGE

200
Success Response
{
  "statusCode": "IN_PROGRESS",
  "statusMessage": "Operation in progress.",
  "operationStart": "2019-07-25T10:17:42.004Z",
}

200
Success Response
{
  "statusCode": "OK",
  "statusMessage": "Operation 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
      }
    ]
  }
}

200
Information Response
{
  "statusCode": "OK",
  "statusMessage": "Operation finished successfully.",
  "operationStart": "2019-07-25T10:17:42.004Z",
  "operationEnded": "2019-07-25T10:17:42.060Z",
  "result": {
    "statusMessage": "Distributed system has no regions that can be rebalanced."
  }
}

404
Not Found Response
{
  "statusCode": "ENTITY_NOT_FOUND",
  "statusMessage": "Operation '12345678' does not exist."
}
  • No labels