RESTful API Best Practices
The following are helpful tips and recommendations that are meant to improve the performance and security of your app.
Security Considerations
The customer information that is provided by Login with Amazon to your app is valuable, and precautions must be taken to ensure that the data stays confidential. The Login with Amazon protocol makes extensive use of HTTPS to protect communications between the user and Amazon, as well as between your app and Amazon.
The Amazon Drive API forces secure (SSL) communication for all requests and responses. Requests sent to non-Amazon servers result in certificate failures. Your app should verify that the certificate is from Amazon while using SSL.
To learn more about security threats that go beyond using HTTPS and how you are able to prevent attackers from gaining valuable customer information, see the Security Considerations section in the Login with Amazon Developer guide.
Finding Root Node
Leverage filters in list request.
GET: /nodes?filters=isRoot:true
Caching Content
Caching content, especially the getEndpoint object and the listChildren object, is recommended. However, no piece of data is able to be retained for more than 30 days without being refreshed.
Use localId in Post Requests
In your app, every localId is mapped to a single Amazon Drive nodeId. A create request with the same localId fails with an error response that contains the HTTP Status Code of 409 Conflict.
Therefore, you should associate the localId as a global unique identifier for each file, and use it to achieve de-duplication that satisfies the user request.
Client Request Retry guidance
This section provides guidance for clients that use the RESTful Amazon Drive API in the event of an error response to a method request.
Types of Failures
The RESTful Amazon Drive API provide an HTTP interface, and HTTP defines ranges of HTTP Status Codes for different types of error responses. The client errors are indicated by HTTP Status Code class of 4xx, and the service errors are indicated by HTTP Status Code class of 5xx.
Client responses to errors with the HTTP Status Code class of 4xx
An HTTP Status Code class of 4xx indicates that the service (Amazon Drive) believes there is a problem with the request sent from the client that prevents the request from being fulfilled. The request should not be retried without changes that attempt to fix the problem. Such a modified request may be retried immediately.
Example: When attempting to download a file, there are a number of reasons that a client may receive an HTTP Status Code of 404 Not Found.
- The node id may not be valid.
- The node may be deleted.
- A pre-authenticated URI may have expired.
None of these are recoverable and the same request should not be retried.
Client responses to errors with the HTTP Status Code class of 5xx
An HTTP Status Code class of 5xx indicates that the service (Amazon Drive), or an intermediary such as a load balancer, failed to process the request for a reason that may have nothing to do with the request from a client.
In the particular case of a request overload, the Amazon Drive attempts to respond with an HTTP Status Code of 503 Service Unavailable. On receipt of an HTTP Status Code of 503 Service Unavailable, a client should delay resending the failed request for a period of time. The exact algorithm for computing the delay (backoff period) is defined as follows.
While you app waits for the backoff period to end, other requests to the method should be held until after a successful retry. Delaying requests may be difficult for a client that sends concurrent requests. In that case, the client may set the backoff delay at whatever scope is feasible (such as thread, connection, or request queue), as long as the action taken by the client on receipt of a series of error responses with the HTTP Status Code of 503 Service Unavailable is to slowdown all of the requests sent from the client to the specified method.
Sometimes a particular request may result in a response that contains the HTTP Status Code class of 5xx due to a bug in the server, while other requests to the same method respond successfully. Example:
In order to prevent a single request from blocking all others, the client may try a different request in lieu of retrying the failed request, as long as the new request honors the same backoff period. After a successful request to the same method, the client may abandon the original request and resume function.
If an error response that is returned after a method request is part of a related sequence of method requests, a client should ideally apply the backoff policy described above to the entire sequence rather than to an individual method.
An HTTP Status Code of 503 Service Unavailable does not specifically indicate that the service (Amazon Drive) is overloaded with requests, but it may indicate that subsequent requests are unlikely to be successful. Sending subsequent requests in this case, only consumes bandwidth and CPU cycles unnecessarily. For this reason, clients should respond to the HTTP Status Code class of 5xx in the same way they respond to an HTTP Status Code of 503 Service Unavailable.
Backoff algorithm
Clients that use the Amazon Drive API should use a truncated exponential backoff strategy with randomization when in backoff mode due to method request failures. The recommended algorithm is as follows.
B ~ Random(0, 2 ^min(n, 8)) seconds
The backoff period B in seconds is distributed randomly between 0 and 2 to the nth-power, where n is the zero-based retry count or 8, whichever is less. The listed algorithm results in the following delays before retries:
| Retry (zero-based) | Minimum retry delay (seconds) | Mean delay | Maximum delay |
|---|---|---|---|
| 0 | 0 | 0.5 | 1 |
| 1 | 0 | 1 | 2 |
| 2 | 0 | 2 | 4 |
| 3 | 0 | 4 | 8 |
| 4 | 0 | 8 | 16 |
| 5 | 0 | 16 | 32 |
| 6 | 0 | 32 | 64 (1:04) |
| 7 | 0 | 64 (1:04) | 128 (2:08) |
| 8 | 0 | 128 (2:08) | 256 (4:16) |
| >8 | 0 | 128 (2:08) | 256 (4:16) |
If a request that is sent at regular intervals fails, then the client may follow the recommended retry backoff algorithm, or simply abandon the request and try again when the next interval has passed. Example: If a client sends a method request every minute during normal functionality and that request fails returns an error response, then the client is not required to backoff more than the regular one minute interval.
General Guidance
The client should include a custom User-Agent HTTP header that identifies the app and version.
Even successful requests should not be made at a rate that may compromise the performance or behavior of the Amazon Drive. If a client is required to repeat the same request more than once a minute, then the Amazon Drive team should be engaged to discuss and approve an elevated service-level agreement.
Support
If you have any questions, see the Developer Forum.