RESTful API Best Practices

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

1	GET: {{metadataUrl}}/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 Cloud 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 Cloud Drive API in the event of an error response to a method request.

Types of Failures

The RESTful Amazon Cloud 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 Cloud 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 Cloud 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 Cloud 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: A specific image may cause the code for cutting a thumbnail cutting to fail consistently. Because this is a bug in the service and not a problem with the request, the response contains an HTTP Status Code of 500 Service Unavailable. But in this case retrying is not going to help and will continue until the bug in the service is fixed. The client should detect the repeated failures, abandon the request, and try another image. The next image is likely to succeed, and the client should be able to resume normal function.

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

1	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 Cloud Drive. If a client is required to repeat the same request more than once a minute, then the Amazon Cloud Drive team should be engaged to discuss and approve an elevated service-level agreement.