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 prefer HATEOASwill add related HATEOAS link to each configuration responses, such as: return resource link in the response of create/updatelist/deleteget; 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
Long running request:
Rebalance
rebalance request and response:
Code Block |
---|
POST https://localhost/operations/rebalance
HTTP/1.1 202 Accepted
Location: https://localhost/operations/12336 |
...
HTTP/1.1 202 Accepted
Location: https://localhost/operations/12336
subsequent rebalance request 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: http GET https://localhost/operations/12336
response of running rebalance:
...
HATEOAS link
for every relation between entities, will be shown as links in the output of response.
such as the followings, it is a links part of region and it shows that the related links of current entity(region):
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
"links": {
"indexes": "http://127.0.0.1:7070/management/experimental/regions/REGION6/indexes",
"self": "http://127.0.0.1:7070/management/experimental/regions/REGION6",
"list": "http://127.0.0.1:7070/management/experimental/regions"
} |
some guideline for links:
- 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:
- 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:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"statusCode": "OK",
"result": [{
"id": "region-with-proxy",
"groups": [{
"configuration": {
"group": "group2",
"name": "region-with-proxy",
"type": "PARTITION"
},
"runtimeInfo": [{
"entryCount": 10
}]
}, {
"configuration": {
"group": "group1",
"name": "region-with-proxy",
"type": "PARTITION_PROXY"
},
"runtimeInfo": [{
"entryCount": 10
}]
}],
"links": {
"indexes": "http://localhost:22500/management/v1/regions/region-with-proxy/indexes",
"self": "http://localhost:22500/management/v1/regions/region-with-proxy",
"list": "http://localhost:22500/management/v1/regions"
}
}, {
"id": "region-in-single-group",
"groups": [{
"configuration": {
"group": "group1",
"name": "region-in-single-group",
"type": "PARTITION"
},
"runtimeInfo": [{
"entryCount": 20
}]
}],
"links": {
"indexes": "http://localhost:22500/management/v1/regions/region-in-single-group/indexes",
"self": "http://localhost:22500/management/v1/regions/region-in-single-group",
"list": "http://localhost:22500/management/v1/regions"
}
}, {
"id": "region-in-cluster",
"groups": [{
"configuration": {
"name": "region-in-cluster",
"type": "PARTITION"
},
"runtimeInfo": [{
"entryCount": 0
}]
}],
"links": {
"indexes": "http://localhost:22500/management/v1/regions/region-in-cluster/indexes",
"self": "http://localhost:22500/management/v1/regions/region-in-cluster",
"list": "http://localhost:22500/management/v1/regions"
}
}, {
"id": "region-in-multiple-groups",
"groups": [{
"configuration": {
"group": "group2",
"name": "region-in-multiple-groups",
"type": "PARTITION"
},
"runtimeInfo": [{
"entryCount": 0
}]
}, {
"configuration": {
"group": "group1",
"name": "region-in-multiple-groups",
"type": "PARTITION"
},
"runtimeInfo": [{
"entryCount": 0
}]
}],
"links": {
"indexes": "http://localhost:22500/management/v1/regions/region-in-multiple-groups/indexes",
"self": "http://localhost:22500/management/v1/regions/region-in-multiple-groups",
"list": "http://localhost:22500/management/v1/regions"
}
}]
} |
References
...
response of a finished rebalance : 200 Ok,
{ "operationType": "rebalance", "startTime": "1287364876", "endTime" : "232353232", "status": "successful" }
cancel request: http DELETE https://localhost/operations/12336
response: 200 Ok. { "operationType": "rebalance", "startTime": "1287364876", "endTime" : "232353232", "status": "cancelled" }
if it's already finished, the response should be: { "operationType": "rebalance", "startTime": "1287364876", "endTime" : "232353232", "status": "successful" }
How to purge the operations/????
some refer:
1 https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md
...