Details
-
Improvement
-
Status: Open
-
Minor
-
Resolution: Unresolved
-
None
-
None
-
None
-
None
Description
1a) Use the appropriate HTTP 2xx set of Reply Statuses
- 200 OK for Success on GET/PUT
- 201 CREATED for POST that actually Creates a new Resource
- 204 For Successful DELETE (This is not a Hard & Fast - 200 may be OK)
1b) Investigate usage of PATCH & HEAD as additions to the current API.
Currently PUTs are used make partial updates. For "true rest" (whatever that means) PUT corresponds to a Whole resource REPLACE.
the PATCH RFC was practically invented for this purpose http://tools.ietf.org/html/rfc5789
Provide a HEAD call as a "lightweight" way for the clients to poll for info where it makes sense.
2) Implement Pagination, Throttling, Caching with ETags & Good Headers to make interacting with the API to be Consistent with User Agents
Pagination - (Need) - When I have a Cluster with hundreds of Hosts - I need to ability to be able to consume this content in a Consistent Idempotent way
Throttling - (Need) - The API should not become an unwitting Denial-Of-Service Vector with tons of Calls triggering slowdowns on the Management (Ambari itself). There needs to be a configurable Throttling Default (using Custom Headers possibly). Twitter Rate limiting API is one of the better implementations of this using custom headers:
https://dev.twitter.com/docs/rate-limiting/1.1
Caching & ETags - (Need) - these can help clients of the API make intelligent calls & reduce the amount of work & chattiness of the API & Server
Good Headers on Responses - Header tags such as Cache-control, Max-age etc will help clients make the right handling choices.
[Longer Term]
3) Begin work on HATEOS - for example a call to GET on Clusters could return what operations are supported for which Cluster as Links. This makes the API self-Discoverable to a certain extent.
(Could supply more details as required.)