Amazon SimpleDB
Developer Guide (API Version 2009-04-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

API Usage

This section provides a high-level overview of the Amazon SimpleDB API. It describes API conventions, API versioning used to minimize the impact of service changes, and API-specific information for making REST requests.

API Conventions

Overview

This topic discusses the conventions used in the Amazon SimpleDB API reference. This includes terminology, notation, and any abbreviations used to describe the API.

The API reference is broken down into a collection of Actions and Data Types.

Actions

Actions encapsulate the possible interactions with Amazon SimpleDB. These can be viewed as remote procedure calls and consist of a request and response message pair. Requests must be signed, allowing Amazon SimpleDB to authenticate the caller.

Data Types

Values provided as parameters to the various operations must be of the indicated type. Standard XSD types (like string, boolean, int) are prefixed with xsd:. Complex types defined by the Amazon SimpleDB WSDL are prefixed with sdb:.

WSDL Location and API Version

The Amazon SimpleDB API is published through a Web Services Description Language (WSDL) and an XML schema document. The version of the Amazon SimpleDB API supported with this document is 2009-04-15.

The Amazon SimpleDB WSDL is located at: http://sdb.amazonaws.com/doc/2009-04-15/AmazonSimpleDB.wsdl.

The Amazon SimpleDB schema is located at: http://sdb.amazonaws.com/doc/2009-04-15/AmazonSimpleDB.xsd.

Some libraries can generate code directly from the WSDL. Other libraries require a little more work on your part.

API Versions

All Amazon SimpleDB API operations are versioned. This minimizes the impact of API changes on client software by sending back a response that the client can process. New versions are designed to be backward-compatible with older API revisions. However, there might be occasions where an incompatible API change is required. Additionally, newer API responses might include additional fields and, depending on how the client software is written, it might not be able to handle additional fields. Including a version in the request guarantees that it will always be sent a response that it expects.

Each API revision is assigned a version in date form. This version is included in the request as a version parameter when using REST. The response returned by Amazon SimpleDB honors the version included in the request. Fields introduced in a later API version are not returned in the response.

The WSDL for each supported API version is available using the following URI format:

http://sdb.amazonaws.com/doc/<api-version>/AmazonSimpleDB.wsdl

Specifying the API Version

For all requests, you must explicitly request the API version you want to use. Specifying the version ensures that the service does not return response elements that your application is not designed to handle.

In REST requests, you include the Version parameter.

http://sdb.amazonaws.com
?Action=CreateDomain
&AWSAccessKeyId=[valid access key id]
&DomainName=MyDomain
&SignatureVersion=2
&SignatureMethod=HmacSHA256
&Timestamp=2010-01-25T15%3A01%3A28-07%3A00
&Version=2009-04-15
&Signature=[valid signature]

API Error Retries

This section describes how to handle client and server errors.

Note

For information on specific error messages, see API Error Codes

Client Errors

REST client errors are indicated by a 4xx HTTP response code.

Do not retry client errors. Client errors indicate that Amazon SimpleDB found a problem with the client request and the application should address the issue before submitting the request again.

Server Errors

For server errors, you should retry the original request.

REST server errors are indicated by a 5xx HTTP response code.

Retries and Exponential Backoff

Numerous components on a network, such as DNS servers, switches, load-balancers, and others can generate errors anywhere in the life of a given request.

The usual technique for dealing with these error responses in a networked environment is to implement retries in the client application. This technique increases the reliability of the application and reduces operational costs for the developer.

You should retry original requests that receive server errors (5xx). However, client errors (4xx) indicate you need to revise the request itself to correct the problem before trying again.

In addition to simple retries, we recommend using an exponential backoff algorithm for better flow control. The concept behind exponential backoff is to use progressively longer waits between retries for consecutive error responses. For example, up to 400 milliseconds before the first retry, up to 1600 milliseconds before the second, up to 6400 milliseconds before third, and so on.

Following is a workflow showing retry logic. The workflow logic first determines if the error is a server error (5xx). Then, if the error is a server error, the code retries the original request.

currentRetry = 0
DO
  execute Amazon SimpleDB request
  IF status = success
    set retry to false
  ELSE IF status = server error (5xx)
    set retry to true
    currentRetry = currentRetry + 1
    wait for a random delay between 0 and (4^currentRetry * 100) milliseconds
  ELSE
    set retry to false and fix client error (4xx)
WHILE (retry = true AND currentRetry < MaxNumberOfRetries)  // limit retries

Following is a snippet of Java code that implements the logic and exponential backoff.

 boolean shouldRetry = true;
 int retries = 0;
 do {
   try {
    /* Submit request to Amazon SimpleDB*/
     if (status == HttpStatus.SC_OK) {
       shouldRetry = false;
      /* Process successful response from Amazon SimpleDB */
     } else {
       if (status == HttpStatus.SC_INTERNAL_SERVER_ERROR
	      || status == HttpStatus.SC_SERVICE_UNAVAILABLE) {
	 shouldRetry = true;
	 long delay = (long) (Math.random() * (Math.pow(4, retries++) * 100L));
	 try {
	   Thread.sleep(delay);
	 } catch (InterruptedException iex){
	   log.error("Caught InterruptedException exception", iex);
	 }
       } else {
	 shouldRetry = false;
	/* Process 4xx (Client) error */
       }
     }
   } catch (IOException ioe) {
     log.error("Caught IOException exception", ioe);
   } catch (Exception e) {
     log.error("Caught Exception", e);
   } finally {
     /* Perform clean-up as necessary */
   }
 } while (shouldRetry && retries < MAX_NUMBER_OF_RETRIES);

The AWS SDKs that support Amazon SimpleDB implement retries and exponential backoff. For example, to download Java code that implements the exponential backoff algorithm, see the AWS SDK for Java.