Page History

Table of Contents

...

General Guidelines:

• for unknown attributes in the request, we will throw an error with a whole list of all of thema bad request error.

• for all the response, we will add related HATEOAS link to each configuration responses, such as: return resource link in the response of create/list/get; add resource url for sub resources(region/indexes). more detail,  please read "HATEOAS link" in Guidelines for Cluster Management service

• http status code: 201 and 409 for create, 200 and 404 for delete,  200 and 404 for put to update

• camelCase is for all the key in the request and response body

...

• the "links" part is sibling of "configuration" and "runtimeInfo"
• all the related resources will be shown in "links" part
• every link includes whole address,  begins from "http"/"https"
• there must be a "self" link in every "links",  the "self" means current resource(entity)
• there must be a "list" link in every "links",  it means the resources (list)
• other link in "link" part must be plural(“-es”)

Long running request:

Rebalance

Rebalance request and response:

POST https://localhost/operations/rebalance

HTTP/1.1 202 Accepted
Location: https://localhost/operations/12356

Subsequent rebalance operations would get the same result: (if a rebalance is already going on, the request is simply accepted, and returns the running rebalance's operation status link)

If the previous rebalance request is already finished, a new rebalance will be triggered, and a new operation status link will be sent back to the user

Status request for a running operation: 

GET https://localhost/operations/12356

HTTP/1.1 200 OK

{
  "operationType": "rebalance",
  "startTime": "1287364876",
  "status": "running",
  "cancelLink" : "/operations/12356"
}

Response of a completed rebalance operation:

GET https://localhost/operations/12356

HTTP/1.1 200 OK

{
  "operationType": "rebalance",
  "startTime": 1287364876,
  "endTime": 232353232,
  "status": "successful"
}

Status of successful responses will be kept around for a set period of time, after that, the record will be deleted. and a response of 404 will be returned back to the user.

To cancel a request:

DELETE https://localhost/operations/12356

HTTP/1.1 200 OK

{ 
  "operationType": "rebalance",
  "startTime": 1287364876,
  "endTime": 232353232,
  "status": "cancelled"
}

If the operation is already finished, the response status should be:  "status": "successful" 

To view all current operations:

• operations that are long running should not hold up the http connection for the entirety of the operations. The operation will be started and then the response should go back to the user signifying "operation started" with a link to check the status of the operation.
• User will issue the request to the "status" link to check the operation status.

Groups:

When an entity is defined in multiple groups, for example, a region can be defined in multiple groups, when we issue a GET to the "/regions/regionA", it's expected that we should only get one entity back. But since the region is defined in multiple groups, and could potentially have different configurations per group, the configuration for this region can be multiple. So we should try to lump all the configurations for one entity into one entity response back to the user. 

Here is an example how the response would look like to the user when a region belongs to multiple groups:

{
	"statusCode": "OK",
	"result": {
		"id": "MyRegion",
		"groups": [{
			"configuration": {
				"group": "group2",
				"name": "MyRegion",
				"type": "PARTITION"
			},
			"runtimeInfo": [{
				"entryCount": 0
			}]
		}, {
			"configuration": {
				"group": "group1",
				"name": "MyRegion",
				"type": "PARTITION_PROXY"
			},
			"runtimeInfo": [{
				"entryCount": 0
			}]
		}],
		"links": {
			"indexes": "http://localhost:22500/management/v1/regions/MyRegion/indexes",
			"self": "http://localhost:22500/management/v1/regions/MyRegion",
			"list": "http://localhost:22500/management/v1/regions"
		}
	}

GET https://localhost/operations/

HTTP/1.1 200 OK

{
  operations: [
    {
      "operationType": "rebalance",
      "startTime": 1287364876,
      "status": "running",
      "cancelLink" : "/operations/12356"
    },
    {
      "operationType": "gii",
      "startTime": 123455555,
      ...
    }
  ]
}

References:

1 https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md

...