Guidelines for Cluster Management service

Something we will follow:

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

• for all the response, we prefer HATEOAS, such as: return resource link in the response of create/update/delete; add resource url for sub resources(region/indexes)

• 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:

POST https://localhost/operations/rebalance

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

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 for a running operation: 

GET https://localhost/operations/12356

HTTP/1.1 200 OK

{
  "operationType": "rebalance",
  "startTime": "1287364876",
  "status": "running",
  "cancelMethod": "delete",
  "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"
}

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

2 https://developer.github.com/v3/

3 https://codeplanet.io/principles-good-restful-api-design/

4 https://blog.florimond.dev/restful-api-design-13-best-practices-to-make-your-users-happy

5 https://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/

6 https://google.github.io/styleguide/jsoncstyleguide.xml