AWS SDK for Node.js v0.9.8-pre.9

Release Notes>JavaScript>AWS SDK for Node.js v0.9.8 pre.9
This release adds support for bound parameters, API versioning, IAM roles for EC2 instances, proxy and low-level HTTP option configuration, and support for the 2012-08-10 API version of DynamoDB. This release contains backwards-incompatible changes, so upgrading notes are also provided.

Details

Created On: April 18, 2013 5:14 PM GMT
Last Updated: April 18, 2013 5:22 PM GMT

Latest Version

npm install aws-sdk

Upgrading Notes

Change Description
AWS.Request.client renamed to AWS.Request.service

This is a backward incompatible change that is scoped to the AWS.Request class. If you use this propertry, you can upgrade with the following change:

request.client.someProperty to request.service.someProperty

Client and .client properties deprecated

SERVICE.Client and service.client properties remain for backward-compatibility, but are now deprecated and no longer documented. They may be removed in a 1.0 release. To migrate these properties, change:

new AWS.S3.Client(...) to new AWS.S3(...)

and/or:

s3.client.listObjects(...) to s3.listObjects(...)

New Amazon DynamoDB API version

Version 0.9.8-pre.9 of the AWS SDK for Node.js includes a new Amazon DynamoDB API version (2012-08-10) that contains backward-incompatible changes from the previous API version (2011-12-05). By default, the SDK will load the latest available API version when calling new AWS.DynamoDB().

Migrating operations

In general, the API changes mostly affect the way you create and get items from a table, however other operations are also affected. For a more in-depth look at the new API, please see the Amazon DynamoDB API reference.

Creating tables

Creating a table changes from passing these parameters (with id as the string hash key):

db.createTable({
  TableName: 'myTable',
  KeySchema: {
    HashKeyElement: { AttributeName: 'id', AttributeType: 'S' }
  },
  ...
}, function() { ... });

Into the following:

db.createTable({
  TableName: 'myTable',
  AttributeDefinitions: [
    { AttributeName: 'id', AttributeType: 'S' }
  ],
  KeySchema:[
    { AttributeName: 'id', KeyType: 'HASH' }
  ],
  ...
}, function() { ... });

Getting items

For the getItem operation, the arguments mostly change by dropping the HashKeyElement and RangeKeyElement arguments, instead replacing them with the actual hash key name in the schema. For example, the following getItem call:

db.getItem({TableName: 'myTable', Key: {HashKeyElement: {S: key}}}, ...);

Turns into this, where id is our hash key:

db.getItem({TableName: 'myTable', Key: {id: {S: key}}}, ...);

Output from these requests will similarly drop HashKeyElement parameters from output, replacing with the actual hash key name.

Locking into the 2011-12-05 API

If you want to continue using the Amazon DynamoDB 2011-12-05 API, you can lock your API version in your global configuration with apiVersions, or directly when constructing a service object with the apiVersion option:

// Locking AWS.DynamoDB globally in AWS.config
AWS.config.apiVersions = {
  dynamodb: '2011-12-05'
};

// Directly on a service object
var db = new AWS.DynamoDB({apiVersion: '2011-12-05'});

The apiVersions option can also be loaded from an external JSON configuration file with AWS.config.loadFromPath():

{
  "region": "us-west-2",
  "accessKeyId": "<YOUR_ACCESS_KEY_ID>",
  "secretAccessKey": "<SECRET>",
  "apiVersions": {
    "dynamodb": "2011-12-05"
  }
}

This file can be loaded with:

AWS.config.loadFromPath('path/to/config.json');

New Features

Change Description
Removed Client Property

Deprecated Client and .client properties. Also renames AWS.Request.client to AWS.Request.service to be consistent with the new service concept. This is a backward-incompatible change. Please see the "Upgrading Notes" at the top of this document for more information.

Bound Parameters

You can now create service objects with a params hash that contains top level parameters bound to all subsequent operation calls. For example, to operate on an AWS.S3 object, you can use:

var s3obj = new AWS.S3({params: {Bucket: 'bucket', Key: 'key'}});

// no bound params passed to put or get calls
s3obj.putObject({Body: 'text'}, function() {
  s3obj.getObject(function(err, data) {
    console.log("Got the data back", data.Body.toString());
  });
});

Note that only toplevel parameters can be bound. These parameters will also be automatically ignored for operations that do not use these parameters. For example, we can still use the s3obj variable to call listObjects(), even though that operation does not accept a Key parameter:

s3obj.listObjects(function(err, data) {
  console.log("Objects in my bucket", data);
});

API Versioning

Added support for locking service objects to specific API versions through the apiVersions global configuration parameter, or the apiVersion service specific parameter. By default, the value for all services is 'latest', which means the latest API version will be used. This value can be changed per-service. For example, to lock your AWS.DynamoDB client to the 2011-12-05 API version, you can add the following to your global configuration:

AWS.config.apiVersions = {
  dynamodb: '2011-12-05'
};

Note that the "dynamodb" value is the "service identifier" of the AWS.DynamoDB service object. Service identifiers can be found in the AWS SDK for Node.js API documentation.

You can also use the apiVersion property when creating a AWS.DynamoDB object:

var db = new AWS.DynamoDB({apiVersion: '2011-12-05'});

Note that version constraint values are fuzzy, so it is possible to lock into a specific release date (globally and per-service) rather than an API version date. This ensures that you do not use any service API versions that are newer than the specified lock date. For instance, if you begin developing your project on 2013-04-18, you can lock into this version by specifying this date as your apiVersion (or apiVersions):

// global for all services
AWS.config.apiVersion = '2013-04-18';

// override some service API versions
AWS.config.apiVersions = {
  dynamodb: '2011-12-05' // use an older API
};

Service documentation is also now updated to provide examples on constructing a service object with the appropriate version lock information for each available API version.

IAM Roles for EC2

Credentials will now be automatically loaded from an Amazon EC2 instance metadata service if IAM roles are configured on an Amazon EC2 instance. This allows for zero-configuration deployments.

AWS.RDS Update

Updated AWS.RDS to the latest API version (2013-02-12).

AWS.DynamoDB (2012-08-10)

Added a new API version of the AWS.DynamoDB service. By default, creating a AWS.DynamoDB object will use this API.

Note that this API is not compatible with the previous version. For more information, see the "Upgrading Notes" at the top of this document.

Domain Support

Added basic support for the Node.js "domain" module (GitHub issue #75).

Proxy Support

Added proxy support to the SDK. To set a global proxy, configure the proxy endpoint in the AWS.Config.httpOptions.proxy setting like so:

AWS.config.update({
  httpOptions: {
    proxy: 'http://localhost:8080'
  }
});

// transparently uses local proxy
var s3 = new AWS.S3();
s3.client.getObject(...);

Config.httpOptions

Added httpOptions configuration parameter that allows for setting of HTTP-level request options such as:

  • timeout — used to set the socket timeout (in milliseconds).
  • agent — used to override the http.Agent object used in the HTTP requests. Defaults to the http.globalAgent object for HTTP connections and a custom HTTPS agent with peer certificate verification on for HTTPS connections.

Sample usage: Setting a custom timeout value of 500ms on Amazon S3 operations:

var s3 = new AWS.S3({httpOptions: {timeout: 500}});
s3.client.getObject(params, function(err, data) {
  // err.code can be a TimeoutError
});

Creating a custom connection pool for a specific client over HTTP:

var http = require('http');
var agent = new http.Agent({maxSockets: 20}); // pool size = 20
var options = {sslEnabled: false, httpOptions: {agent: agent}};
var s3 = new AWS.S3(options);

Note that increasing the connection pool size over HTTPS connections increases overhead for short-running processes.

Redirect Support

The SDK will now follow all 3xx redirects with no delay. This change also adds the AWS.Config.maxRedirects option to control maximum number of redirects to follow before giving up. AWS.Response.redirectCount is also available to check the number of redirects attempted during the request.

Asynchronous Credentials

Credentials can now be loaded asynchronously through the AWS.Config.getCredentials method.

AWS.MetadataService

Added AWS.MetadataService client to query Amazon EC2 instance metadata. To make a request, call:

svc = new AWS.MetadataService();
svc.request('/path/to/resource', function (err, data) {
  console.log(err); // any error data
  console.log(data); // string data returned by instance metadata server
});

Resolved Issues

Change Description
Parameter Validation / Serialization

Fixed issue where passing UNIX timestamps to services that accepted this timestamp format would fail in parameter validation and type conversion (GitHub issues #97, #99).

Error Propagation

Propagate errors from all callbacks up to main runloop (GitHub issue #74).

Client config

Fixed an issue where credentials were being ignored when initialized via service or client objects. (GitHub issue #72)

Supported API Versions

This release of the SDK supports the following API versions:

Service API Version
Amazon CloudFront 2012-05-05
Amazon CloudSearch 2011-02-01
Amazon CloudWatch 2010-08-01
Amazon DynamoDB 2011-12-05
2012-08-10
Amazon Elastic Compute Cloud 2013-02-01
Amazon Elastic MapReduce 2009-03-31
Amazon Elastic Transcoder 2012-09-25
Amazon ElastiCache 2012-11-15
Amazon Glacier 2012-06-01
Amazon Redshift 2012-12-01
Amazon Relational Database Service (Beta) 2013-02-12
Amazon Route 53 2012-12-12
Amazon Simple Email Service 2010-12-01
Amazon Simple Notification Service 2010-03-31
Amazon Simple Queue Service 2012-11-05
Amazon Simple Storage Service 2006-03-01
Amazon Simple Workflow Service 2012-01-25
Amazon SimpleDB 2009-04-15
Auto Scaling 2011-01-01
AWS CloudFormation 2010-05-15
AWS Data Pipeline 2012-10-29
AWS Direct Connect 2012-10-25
AWS Elastic Beanstalk 2010-12-01
AWS Identity and Access Management 2010-05-08
AWS Import/Export 2010-06-01
AWS OpsWorks 2013-02-18
AWS Security Token Service 2011-06-15
AWS Storage Gateway 2012-06-30
Elastic Load Balancing 2012-06-01
©2014, Amazon Web Services, Inc. or its affiliates. All rights reserved.