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

Compare with Current View Page History

« Previous Version 15 Next »

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). 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

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

example output of links
            "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:

  • 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)
  • the "links" part is sibling of "configuration" and "runtimeInfo"
  • 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:

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/

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

  • No labels