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.
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 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.
Values provided as parameters to the various operations must be of the indicated type. Standard XSD types (like
int) are prefixed with xsd:. Complex types defined by the
Amazon SimpleDB WSDL are prefixed with
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.
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:
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=
API Error Retries
This section describes how to handle client and server errors.
For information on specific error messages, see API Error Codes
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.
For server errors, you should retry the original request.
REST server errors are indicated by a 5xx HTTP response code.
Retries and Exponential Backoff
The AWS SDKs that support Amazon SimpleDB implement retries and exponential backoff. For more information, see Error Retries and Exponential Backoff in the AWS General Reference.