# Migrating from AWS SDK for Ruby version 1 or 2 to AWS SDK for Ruby version 3
<a name="migrating-to-v3"></a>

This topic includes details to help you migrate from version 1 or 2 of the AWS SDK for Ruby to version 3.

## Side-by-side usage
<a name="side-by-side-usage"></a>

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](http://ruby.awsblog.com/post/TxFKSK2QJE6RPZ/Upcoming-Stable-Release-of-AWS-SDK-for-Ruby-Version-2) 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
<a name="general-differences"></a>

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
<a name="client-differences"></a>

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
<a name="resource-differences"></a>

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.**