[jira] [Created] (AMBARI-1778) ReST API Suggested Improvements/New features

["Amit Naik (JIRA)" <ji...@apache.org>]

Amit Naik created AMBARI-1778:
---------------------------------

             Summary: ReST API Suggested Improvements/New features 
                 Key: AMBARI-1778
                 URL: https://issues.apache.org/jira/browse/AMBARI-1778
             Project: Ambari
          Issue Type: Improvement
            Reporter: Amit Naik
            Priority: Minor


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


--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira