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 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)
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 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:
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
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/