Introducing Support for Generating Ruby SDKs in Amazon API Gateway

We’re excited to announce support for generating Ruby SDKs from Amazon API Gateway. The Ruby SDKs you generated are compatible with Ruby 1.9 and later. Generated SDKs have first-class support for API keys, custom or AWS Identity and Access Management (IAM) authentication, automatic and configurable retries, exception handling, and all privileges of aws-sdk-core version 3 has as well. In this blog post, we’ll walk through how to create an example API and generate a Ruby SDK from that API. We also explore various features of the generated SDK. In this post, we assume you have some familiarity with API Gateway concepts.

Creating an example API

To start, let’s create an sample API by using the API Gateway console.
Open the API Gateway console, choose Create API, and then choose Example API. Then choose Import to create the example API.

This simple, example API has four straightforward operations:

A GET on the API root resource that returns HTML describing the API
A GET on the /pets resource that returns a list of Pets
A POST on the /pets resource that creates a new Pet
A GET on the /pets/{petId} resource that returns a specific Pet by ID

You can find more information about this example in the API Gateway documentation.

Deploying the API

Next, let’s deploy our API to a stage.
From Actions choose Deploy API.

On the stage deployment page, name the stage Test, and then choose Deploy.

After deploying, the SDK Generation tab is available. For Platform, choose Ruby.
For Service Name, type Pet.

Choose Generate SDK, and then extract the downloaded SDK package.

The following are the configuration options available for the Ruby platform:

Service Name – Used to generate the Ruby gem namespace for your APIs.
Ruby Gem Name – The name of the Ruby gem your generated SDK code will be placed under. If you don’t provide a name, this defaults to the service name in lowercase, with the “sdk” suffix.
Ruby Gem Version – The version number for the generated Ruby gem. If you don’t provide a version number, this defaults to 1.0.0 if not provided.

These are basic Ruby gem configuration options. You can customize your Ruby gemspec in the generated SDK gem later.

Using the generated Ruby SDK gem

Navigate to the location of your downloaded SDK gem. The directory structure looks like the following.

Note
/features and /spec directories are currently left empty for integration and unit tests that you can add to the SDK. The generated SDK is fully documented for operations and shapes in the source code.

Exploring the SDK

Let’s explore the SDK by building a Ruby gem from the generated source, as follows.

# change to /pet-sdk directory
cd pet-sdk

# build the generated gem
gem build pet-sdk.gemspec
# then you can see pet-sdk-1.0.0.gem is available

Then, install the gem, as follows.

gem install pet-sdk-1.0.0.gem

Finally, create the client.

require 'pet-sdk'

client = Pet::Client.new

Features in the client

Now you have your own client that includes multiple features from the official AWS SDK for Ruby. These include default exponential backoff retries, HTTP wire logging options, configurable timeouts, and more.

For example:

require 'pet-sdk'
client = Pet::Client.new(
  http_wire_trace: true,
  retry_limit: 5,
  http_read_timeout: 50
 )

Making API calls

Let’s see all the API methods that are available and use your SDK’s built-in parameter validators to make a successful API call:

client.operation_names
# => [:create_pet, :get_api_root, :get_pet, :get_pets]

# get me all my pets
resp = client.get_pets

You should see a response like the following.

# I want the cat
client.get_pet
# ArgumentError: missing required parameter params[:pet_id]

# providing :pet_id
client.get_pet(pet_id: 2)
# ArgumentError: expected params[:pet_id] to be a String, got value 2 (class: Fixnum) instead.

# fix the value type
resp = client.get_pet(pet_id: "2")

Now you can see a correct response like the following.
If you have some familiarity with the AWS SDK for Ruby, you should find the experience similar to using an AWS service client.

Generate a Ruby SDK from an API

In addition to using the API Gateway console to generate a Ruby SDK, the get_sdk API is available in all of the AWS SDKs and tools, including the AWS SDK for Ruby.

For this example, we assume that you have some familiarity with the AWS SDK for Ruby. You can find a quick introduction to the SDK for Ruby here.

require 'aws-sdk-apigateway'

client = Aws::ApiGateway::Client.new(region: 'us-west-2')
resp = client.get_sdk({
  rest_api_id: MY_REST_API_ID, # required
  stage_name: DEPLOY_STAGE_NAME, # required
  sdk_type: "ruby", # required
  parameters: {
    "service.name" => "PetStore", # required
    "ruby.gem-name" => "pet",
    "ruby.gem-version" => "0.0.1"
  },
})

Final thoughts

This post highlights how to generate a Ruby client SDK for an API in API Gateway, and how to call the API using the generated SDK in an application. For more information about using a generated SDK, see your README.md file in the uncompressed generated SDK gem folder. Details of example usage of your API are also generated in source file documentation blocks.

Feedback

Please share your questions, comments, and issues with us on GitHub. Feel free to open a support ticket with AWS Support if you find an issue with your API model. You can also catch us in our Gitter channel.

AWS Developer Tools Blog