Migrate from version 1 or 2 to version 3 of the Amazon SDK for Ruby - Amazon SDK for Ruby
Side-by-side usageGeneral differencesClient differencesResource differences
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Migrate from version 1 or 2 to version 3 of the Amazon SDK for Ruby

The purpose of this topic is to help you migrate from version 1 or 2 of the Amazon SDK for Ruby to version 3.

Side-by-side usage

It isn’t necessary to replace the version 1 or 2 of the Amazon SDK for Ruby with version 3. You can use them together in the same application. See this blog post for more information.

A quick example follows.

require 'aws-sdk-v1' # version 1
require 'aws-sdk'    # version 2
require 'aws-sdk-s3' # version 3

s3 = AWS::S3::Client.new # version 1
s3 = Aws::S3::Client.new # version 2 or 3

You don’t need to rewrite existing working version 1 or 2 code to start using the version 3 SDK. A valid migration strategy is to only write new code against the version 3 SDK.

General differences

Version 3 differs from version 2 in one important way.

  • Each service is available as a separate gem.

Version 2 differs from version 1 in several important ways.

  • Different root namespace –Aws versus Amazon. This enables side-by-side usage.

  • Aws.config– Now a vanilla Ruby hash, instead of a method.

  • Strict constructor options - When constructing a client or resource object in the version 1 SDK, unknown constructor options are ignored. In version 2, unknown constructor options trigger an ArgumentError. For example:

    # version 1
AWS::S3::Client.new(http_reed_timeout: 10)
# oops, typo'd option is ignored

# version 2
Aws::S3::Client.new(http_reed_timeout: 10)
# => raises ArgumentError

Client differences

There are no differences between the client classes in version 2 and version 3.

Between version 1 and version 2, the client classes have the fewest external differences. Many service clients will have compatible interfaces after client construction. Some important differences:

  • Aws::S3::Client - The version 1 Amazon S3 client class was hand-coded. Version 2 is generated from a service model. Method names and inputs are very different in version 2.

  • Aws::EC2::Client- Version 2 uses plural names for output lists, version 1 uses the suffix _set. For example:

    # version 1
resp = AWS::EC2::Client.new.describe_security_groups
resp.security_group_set
#=> [...]

# version 2
resp = Aws::EC2::Client.new.describe_security_groups
resp.security_groups
#=> [...]

  • Aws::SWF::Client– Version 2 uses structured responses, where version 1 uses vanilla Ruby hashes.

  • Service class renames – Version 2 uses a different name for multiple services:

    • Amazon::SimpleWorkflow has become Aws::SWF

    • Amazon::ELB has become Aws::ElasticLoadBalancing

    • Amazon::SimpleEmailService has become Aws::SES

  • Client configuration options – Some of the version 1 configuration options are renamed in version 2. Others are removed or replaced. Here are the primary changes:

    • :use_ssl has been removed. Version 2 uses SSL everywhere. To disable SSL you must configure an :endpoint that uses http://.

    • :ssl_ca_file is now :ssl_ca_bundle

    • :ssl_ca_path is now :ssl_ca_directory

    • Added :ssl_ca_store.

    • :endpoint must now be a fully qualified HTTP or HTTPS URI instead of a hostname.

    • Removed :*_port options for each service, now replaced by :endpoint.

    • :user_agent_prefix is now :user_agent_suffix

Resource differences

There are no differences between the resource interfaces in version 2 and version 3.

There are significant differences between the resource interfaces in version 1 and version 2. Version 1 was entirely hand-coded, where as version 2 resource interfaces are generated from a model. Version 2 resource interfaces are significantly more consistent. Some of the systemic differences include:

  • Separate resource class – In version 2, the service name is a module, not a class. In this module, it is the resource interface:

    # version 1
s3 = AWS::S3.new

# version 2
s3 = Aws::S3::Resource.new

  • Referencing resources – The version 2 SDK separates collections and individual resource getters into two different methods:

    # version 1
s3.buckets['bucket-name'].objects['key'].delete

# version 2
s3.bucket('bucket-name').object('key').delete

  • Batch operations – In version 1, all batch operations were hand-coded utilities. In version 2, many batch operations are autogenerated batching operations over the API. Version 2 batching interfaces are very different from version 1.