Migrate from version 1 or 2 to version 3 of the AWS SDK for Ruby - AWS SDK for Ruby
Side-by-side usageGeneral differencesClient differencesResource differences

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

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

Side-by-side usage

It isn’t necessary to replace the version 1 or 2 of the AWS 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 AWS. 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:

    • AWS::SimpleWorkflow has become Aws::SWF

    • AWS::ELB has become Aws::ElasticLoadBalancing

    • AWS::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.