aws-sdk 2.0.1 → 2.0.5

package/doc-src/guide/node-making-requests.md

@@ -0,0 +1,309 @@
+# @title Making Requests in Node.js
+
+# Making Requests in Node.js
+
+A "request" to an AWS service includes the full request and response lifecycle
+of a call to an operation on a service object, including any retries that are
+transparently attempted on your behalf. A request is encapsulated in the SDK by
+the `AWS.Request` object. The semantics of a request are described below,
+specifically, the support for callbacks, events, and streaming of raw HTTP
+response data.
+
+## Asynchronous Callbacks
+
+All requests made through the SDK are asynchronous and use a
+callback interface. Each service method that kicks off a request
+can accept a callback as the last parameter with the signature
+`function(error, data) { ... }`. This callback will be called when
+the response or error data is available.
+
+For example, the following service method can be called with
+a standard callback to retrieve the response data or error:
+
+```javascript
+new AWS.EC2().describeInstances(function(error, data) {
+  if (error) {
+    console.log(error); // an error occurred
+  } else {
+    console.log(data); // request succeeded
+  }
+});
+```
+
+The `error` and `data` parameters are described in the "Response Object"
+section below.
+
+Note that if you do not specify a callback, the operation will
+return an `AWS.Request` object that must be manually sent using
+the `send()` method:
+
+```javascript
+// create the AWS.Request object
+var request = new AWS.EC2().describeInstances();
+
+// register a callback to report on the data
+request.on('success', function(resp) {
+  console.log(resp.data); // log the successful data response
+});
+
+// send the request
+request.send();
+```
+
+### The Response Object (`AWS.Response`)
+
+The response object is passed into each callback function so
+that you can access response data. The `AWS.Response` object that
+is passed in contains two important properties to get at this data:
+
+When using the standard callback mechanism, the two properties will
+be made available as parameters on the callback method in the form:
+`function(error, data) { ... }`
+
+#### The `data` property
+
+The `response.data` property contains the serialized object data
+retrieved from the service request. For instance, for an
+Amazon DynamoDB `listTables` method call, the response data might 
+look like this:
+
+```javascript
+> response.data
+{ TableNames: 
+   [ 'table1', 'table2', ... ] }
+```
+
+The `data` property can be null if an error occurs (see below).
+
+#### The `error` property
+
+In the event of a service error (or transfer error), the
+`response.error` property will be filled with the given
+error data in the form:
+
+```javascript
+{ code: 'SHORT_UNIQUE_ERROR_CODE',
+  message: 'Some human readable error message' }
+```
+
+In the case of an error, the `data` property will be null.
+Note that if you handle events that can be in a failure state,
+you should always check whether `response.error` is set
+before attempting to access the `response.data` property.
+
+#### The `request` property
+
+Access to the originating request object is available through this
+property. For example, to access the parameters that were sent
+with a request:
+
+```javascript
+s3.getObject({Bucket: 'bucket', Key: 'key'}).on('success', function(response) {
+  console.log("Key was", response.request.params.Key);
+}).send();
+```
+
+### Simplified Callback Method
+
+Each operation supports a simplified callback that can be passed as the last
+parameter to any service operation. The callback function should
+accept an `error` parameter, followed by the `data` from the response.
+
+For example:
+
+```javascript
+s3.listBuckets(function(error, data) {
+  if (err) {
+    console.log(error); // error is Response.error
+  } else {
+    console.log(data); // data is Response.data
+  }
+});
+```
+
+Prints (assuming the request succeeded):
+
+```javascript
+{ Owner: { ID: '...', DisplayName: '...' },
+  Buckets:
+   [ { Name: 'someBucketName', CreationDate: someCreationDate },
+     { Name: 'otherBucketName', CreationDate: otherCreationDate } ],
+  RequestId: '...' }
+```
+
+The error and data parameters accepted are equivalent to the `error` and
+`data` properties discussed in the `AWS.Response` response object section
+above.
+
+If you are passing parameters to the operation, the callback should be placed
+after the parameters:
+
+```
+s3.getObject({Bucket: 'bucket', Key: 'key'}, function(err, data) {
+  // ...
+});
+```
+
+### AWS.Request Events
+
+You can alternatively register callbacks on events provided by the
+`AWS.Request` object returned by each service operation method.
+This request object exposes the `success`, `error`, `complete`, and `httpData`
+events, each taking a callback that accepts the response object.
+
+Note that if you omit the simplified callback parameter on the operation
+method, you must call `send()` on the returned request object in order to
+kick off the request to the remote server.
+
+#### Event: 'success'
+
+```javascript
+req.on('success', function(response) { ... });
+```
+
+This event triggers when a successful response
+from the server is returned. The response contains a `.data` field
+with the serialized response data from the service.
+
+For example:
+
+```javascript
+s3.listBuckets().done(function(response) {
+  console.log(response.data);
+}).send();
+```
+
+Prints:
+
+```javascript
+{ Owner: { ID: '...', DisplayName: '...' },
+  Buckets: 
+   [ { Name: 'someBucketName', CreationDate: someCreationDate },
+     { Name: 'otherBucketName', CreationDate: otherCreationDate } ],
+  RequestId: '...' }
+```
+
+#### Event: 'error'
+
+```javascript
+req.on('error', function(error, response) { ... });
+```
+
+The `error` event works similarly to the `success` event, except that it
+triggers in the case of a request failure. In this case, `response.data`
+will be `null` and the `response.error` field will be filled with
+the error data. Note that the `error` object is also passed directly
+as the first parameter to the event:
+
+```javascript
+s3.config.credentials.accessKeyId = 'invalid';
+s3.listBuckets().fail(function(error, response) {
+  console.log(error);
+  // or:
+  console.log(response.error);
+}).send();
+```
+
+Prints:
+
+```javascript
+{ code: 'Forbidden', message: null }
+```
+
+#### Event: 'complete'
+
+```javascript
+req.on('complete', function(response) { ... });
+```
+
+The `complete` event triggers a callback in any final state of a request, i.e.,
+both `success` and `error`. Use this callback to handle any request cleanup
+that must be executed regardless of the success state. Note that if you
+do intend to use response data inside of this callback, you must check
+for the presence of `response.data` or `response.error` before attempting
+to access either property. For example:
+
+```javascript
+request.on('complete', function(response) {
+  if (response.error) {
+    // an error occurred, handle it
+  } else {
+    // we can use response.data here
+  }
+}).send();
+```
+
+#### Event: 'httpData'
+
+```javascript
+req.on('httpData', function(chunk, response) { ... });
+```
+
+<p class="note">If you register a <code>httpData</code> callback,
+  <code>response.data</code> will still contain serialized output
+  for the entire request. It will be your responsibility to remove
+  the default 'httpData' listener if you do not wish to have the
+  extra parsing and memory overhead from the built-in handlers.
+</p>
+
+The `httpData` event is used to stream response data from the
+service packet-by-packet. This event is mostly used for large responses,
+when it is inefficient (or impossible) to load the entire response into
+memory.
+
+Note that this event contains an extra `chunk` parameter containing the
+actual data passed on by the server.
+
+## Multiple Callbacks and Chaining
+
+You can register multiple callbacks on any request object. The
+callbacks can be registered for different events, or all for the
+same event. In addition, you can chain callback registration, for
+example:
+
+```javascript
+request.
+  on('success', function(response) {
+    console.log("Success!");
+  }).
+  on('error', function(response) {
+    console.log("Error!");
+  }).
+  on('complete', function() {
+    console.log("Always!");
+  }).
+  send();
+```
+
+The above example will print either "Success! Always!", or "Error! Always!",
+depending on whether the request succeeded or not.
+
+## Streaming Requests
+
+It is possible to stream a request directly to a Node.js Stream object by
+calling the `createReadStream()` method on a request. This returns a wrapper
+to the raw HTTP stream used to manage the request, and this data can be piped
+into any other Node.js stream. This is mostly useful for service operations
+that return raw data in the payload, like Amazon S3's `getObject` operation,
+which can be used to stream data directly into a file with this functionality:
+
+```javascript
+var s3 = new AWS.S3();
+var params = {Bucket: 'myBucket', Key: 'myImageFile.jpg'};
+var file = require('fs').createWriteStream('/path/to/file.jpg');
+s3.getObject(params).createReadStream().pipe(file);
+```
+
+The stream object can be used interchangeably as any other Node.js readable
+Stream object.
+
+### Limitations of Streaming
+
+When streaming data from a request using `createReadStream()`, only the raw
+HTTP data will be returned (the SDK will not do any post-processing on the
+data). Additionally, if the request initially succeeds, retry logic will be
+disabled for the rest of the response due to Node.js inability to rewind most
+streams. This means that in the event of a socket failure in the middle of a
+connection, the SDK will not attempt to retry and send more data to the stream.
+It will be your responsibility to manage this logic in your library or
+application.

package/doc-src/guide/node-services.md

@@ -0,0 +1,159 @@
+# @title Working with Services in Node.js
+
+# Working with Services in Node.js
+
+## Supported Services
+
+The SDK currently supports all available AWS services. Each service object
+in the SDK currently provides low-level access to every API call in the
+respective AWS service. The full list of methods and their parameters are
+documented in the complete API reference documentation (linked from each
+service name in the list below).
+
+The supported services are:
+
+* [AWS.AutoScaling](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/AutoScaling.html)
+* [AWS.CloudFormation](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/CloudFormation.html)
+* [AWS.CloudFront](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/CloudFront.html)
+* [AWS.CloudSearch](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/CloudSearch.html)
+* [AWS.CloudSearchDomain](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/CloudSearchDomain.html)
+* [AWS.DataPipeline](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/DataPipeline.html)
+* [AWS.DirectConnect](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/DirectConnect.html)
+* [AWS.DynamoDB](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/DynamoDB.html)
+* [AWS.EC2](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/EC2.html)
+* [AWS.ElastiCache](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/ElastiCache.html)
+* [AWS.ElasticBeanstalk](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/ElasticBeanstalk.html)
+* [AWS.ELB](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/ELB.html)
+* [AWS.EMR](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/EMR.html)
+* [AWS.ElasticTranscoder](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/ElasticTranscoder.html)
+* [AWS.SES](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/SES.html)
+* [AWS.Glacier](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/Glacier.html)
+* [AWS.IAM](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/IAM.html)
+* [AWS.ImportExport](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/ImportExport.html)
+* [AWS.CloudWatch](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/CloudWatch.html)
+* [AWS.OpsWorks](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/OpsWorks.html)
+* [AWS.RDS](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/RDS.html)
+* [AWS.Redshift](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/Redshift.html)
+* [AWS.Route53](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/Route53.html)
+* [AWS.S3](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/S3.html)
+* [AWS.SimpleDB](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/SimpleDB.html)
+* [AWS.SNS](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/SNS.html)
+* [AWS.SQS](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/SQS.html)
+* [AWS.StorageGateway](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/StorageGateway.html)
+* [AWS.STS](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/STS.html)
+* [AWS.Support](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/Support.html)
+* [AWS.SimpleWorkflow](http://docs.amazonwebservices.com/AWSJavaScriptSDK/latest/frames.html#!AWS/SimpleWorkflow.html)
+
+<div class="clear"></div>
+
+## Constructing a Service
+
+Each service can be constructed with runtime configuration data that is
+specific to that service object. The service-specific configuration data
+will be merged on top of global configuration, so there is no need to
+re-specify any global settings. For example, an EC2 object can be created
+for a specific region:
+
+```javascript
+var ec2 = new AWS.EC2({region: 'us-west-2'});
+```
+
+This object will continue to use the globally provided credentials.
+
+## Locking API Versions
+
+Services released by AWS use API versions to keep track of API compatibility.
+API versions in AWS services can be identified by a `YYYY-mm-dd` formatted
+date string, i.e., 2006-03-01 for Amazon S3. It is recommended to lock into
+an API version for a service if you are relying on it for production code.
+This way, you can isolate yourself from service changes in updates of the
+SDK.
+
+In order to lock into an API version of a given service, simply pass the
+`apiVersion` parameter when constructing the object, for example:
+
+```javascript
+var dynamodb = new AWS.DynamoDB({apiVersion: '2011-12-05'});
+```
+
+Note that versions can also be locked globally by specifying the `apiVersion`
+or `apiVersions` global configuration parameters. This is documented with
+more detail in the {file:node-configuring.md Configuring} section.
+
+### Using the Latest Version
+
+By default, the SDK will select the **latest** available service API version
+when constructing a service object (unless overridden globally). You can
+also force the latest API version to be used by passing the "latest" value
+as the `apiVersion` parameter like so:
+
+```javascript
+var ec2 = new AWS.EC2({apiVersion: 'latest'});
+```
+
+### Fuzzy Versions and Date Locking
+
+Since AWS has many services with many different API versions, the SDK allows
+for the specification of "fuzzy versions" instead of exact API version
+matches. This allows you to specify any date after the API version date,
+and the SDK will look for the *last* available matching API version when
+loading the service object. For instance, you can also load the 2011-12-05
+DynamoDB API by using the following code:
+
+```javascript
+var dynamodb = new AWS.DynamoDB({apiVersion: '2012-04-04'});
+```
+
+Note that 2012-04-04 is later than the first API release (2011-12-05)
+but earlier than the next revision of the API (2012-08-10), so the *first*
+revision will be used.
+
+You can also use this strategy to globally lock your application to a point
+in time. For instance, if you begin developing your application on 2012-07-05,
+you can add the following global `apiVersion` lock value:
+
+```javascript
+AWS.config.apiVersion = '2012-07-05';
+```
+
+This will allow *all* created service objects to use the latest available
+API versions at the specified lock time. You can override any API versions
+if you need a newer version, or if the service had not yet been released,
+by adding the `apiVersion` parameter to the constructor call as normal:
+
+```javascript
+// Amazon Redshift was not yet released in 2012-07-05
+var redshift = new AWS.Redshift({apiVersion: '2012-12-01'});
+```
+
+## Passing Parameters to a Service Operation
+
+When calling a method to a service, you should pass parameters in as
+option values, similar to the way configuration is passed.
+For example, to read an object for a given bucket and key in S3, you
+can pass the following parameters to the `getObject` method:
+
+```javascript
+s3.getObject({Bucket: 'bucketName', Key: 'keyName'});
+```
+
+Note that the full parameter documentation for each method is found
+in each service page in the complete API reference documentation.
+
+## Bound Parameters
+
+Parameters can be automatically passed to service operations by binding them
+directly when constructing the service object. To do this, pass the `params`
+parameter to your constructed service with the map of default parameter
+values like so:
+
+```javascript
+var s3bucket = new AWS.S3({ params: {Bucket: 'myBucket'} });
+```
+
+The `s3bucket` object will now represent an S3 service object bound to a bucket
+named 'myBucket'. Any operation that takes the `Bucket` parameter will now
+have it auto-filled with this value. This value can be overridden by passing
+a new value in the service operation. Additionally, operations that do not
+require a `Bucket` parameter will automatically ignore this bound parameter,
+so the `s3bucket` object can still be used to call `listBuckets`, for instance.