Discovering the EC2 API

05Jul10

I’ve been using the EC2 API quite a lot lately, while working on the Landscape project. The API documentation is excellent, but I want to know how it behaves when things go wrong. What kind of failure is produced when I forget to pass a parameter? What happens when I pass a bogus parameter? How does it behave when I pass numbered parameters that aren’t in sequence, like Name.7=foo&Name.42=bar? How does Amazon’s implementation differ from Eucalyptus or Nova?

I couldn’t find the answers I wanted in the documentation so I wrote a simple tool to invoke a method with an arbitrary set of parameters against an EC2 API endpoint. After sending the request, it prints the HTTP status code and response to the screen. It’s called txaws-discover and is part of the txAWS project. For example, to run the DescribeRegions method simply provide credentials, an endpoint, the method name and whatever parameters you want to pass with it:

$ txaws-discover --key NUJOZS2V6RWQUJ3G8JUT \
    --secret +Ki9Wk5Y4kudFh1EcnB3hthC9PtVU+CcfMJZ4DVl \
    --endpoint https://ec2.us-east-1.amazonaws.com \
    --action DescribeRegions \
    --RegionName.0 us-west-1

This command produces the following output:

HTTP status code: 200


<DescribeRegionsResponse xmlns="http://ec2.amazonaws.com/doc/2008-12-01/">
    <requestId>1e9beacc-0044-4ad6-bd2c-c615351ae46d</requestId>
    <regionInfo>
        <item>
            <regionName>us-west-1</regionName>
            <regionEndpoint>ec2.us-west-1.amazonaws.com</regionEndpoint>
        </item>
    </regionInfo>
</DescribeRegionsResponse>

The credentials and API endpoint can be defined in environment variables to make txaws-discover easier to use:

export AWS_ACCESS_KEY_ID=NUJOZS2V6RWQUJ3G8JUT
export AWS_SECRET_ACCESS_KEY=+Ki9Wk5Y4kudFh1EcnB3hthC9PtVU+CcfMJZ4DVl
export AWS_ENDPOINT=https://ec2.us-east-1.amazonaws.com

With those defined, the command above can be shortened:

$ txaws-discover --action DescribeRegions --RegionName.0 us-west-1

It’s in lp:txaws and has proven to be very helpful as a learning tool.

About these ads


No Responses Yet to “Discovering the EC2 API”

  1. Leave a Comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


Follow

Get every new post delivered to your Inbox.

%d bloggers like this: