Parameter Validation

One of my favorite features of version 2 of the AWS SDK for Ruby (aws-sdk-core gem) is the new parameter validation system. One of the challenges in using an API library is understanding how to specify request parameters. During development stages it is common to make mistakes and to generate errors.

Using the version 1 Ruby SDK (aws-sdk gem), I might want to use the ‘2012-08-10’ Amazon DynamoDB API version to create a table. Without knowing the all of the required parameters I might try something like this:

ddb = AWS::DynamoDB::Client.new(api_version: '2012-08-10')
ddb.create_table(
  table: 'name',
  provisioned_throughput: { read_capacity_units: 'Over 9000!' }
)
#=> raises AWS::Core::OptionGrammar::FormatError: expected integer value for key read_capacity_units

Oops! It’s easy enough to correct that error, but there are more validation errors waiting to raise.

Version 2 Validation

Version 2 of the Ruby SDK aggregates all validation errors and raises them in a single pass.

ddb = Aws::DynamoDB.new(api_version: '2012-08-10')
ddb.create_table(
  table: 'name',
  provisioned_throughput: { read_capacity_units: 'Over 9000!' }
)

# raises the following:

ArgumentError: parameter validator found 6 errors:
  - missing required parameter params[:attribute_definitions]
  - missing required parameter params[:table_name]
  - missing required parameter params[:key_schema]
  - unexpected value at params[:table]
  - missing required parameter params[:provisioned_throughput][:write_capacity_units]
  - expected params[:provisioned_throughput][:read_capacity_units] to be an integer

Each error gives the context as well as information on what needs to be corrected before the request can be sent. I can now correct all of the validation errors in a single pass.

Formatting Examples

Even better, the V2 API documentation gives formatting examples of how to call each operation. Here is a link to the create table method docs with an example.

We’ve been getting a lot of great customer feedback on our GitHub project for the version 2 Ruby SDK. Keep it coming! We would love to hear what you think is missing.