Introducing the AWS Resource APIs for Java

Today we’re excited to announce the first developer preview release of the AWS Resource APIs for Java!

The AWS SDK for Java provides a set of Amazon[Service]Client classes, each exposing a direct mapping of each AWS service’s API. These client objects have a method for each operation that the service supports, with corresponding POJOs representing the request parameters and the response data. Using this “low-level” client API gives you full control over what requests you’re making to the service, allowing you to very tightly control the behavior and performance of your calls to AWS services, but it can also be a bit intimidating to a new user.

With the resource APIs, we’re hoping to improve this experience by providing a higher-level, object-oriented abstraction on top of the low-level SDK clients. Instead of a single client object exposing a service’s entire API, with the resource APIs we’ve defined a class representing each of the conceptual “resources” that you interact with while using a service. These classes expose getters for data about the resource, actions that can be taken on the resource, and links to other related resources. For example, using the EC2 API:

Instance instance = ec2.getInstance("i-xxxxxxxx");
System.out.println(instance.getDnsName());
instance.terminate();

Trying the API

First you’ll need to get your hands on the library. The easiest way to do this is via Maven:

    <dependency>
      <groupId>com.amazonaws.resources</groupId>
      <artifactId>aws-resources</artifactId>
      <version>0.0.1</version>
      <type>pom</type>
    </dependency>

Or alternatively, you can download the preview release here.

Creating a Service

A service object is the entry point for creating and interacting with resource objects. You create service instances by using the ServiceBuilder:

EC2 ec2 = ServiceBuilder.forService(EC2.class)
    .withCredentials(new ProfileCredentialsProvider("test-app"))
    .withRegion(Region.getRegion(Regions.US_WEST_2))
    .build();

Moving on to Resource objects

From the Service instance, you can follow references to resources exposed by the service:

// Get an instance reference by id
Instance instance = ec2.getInstance("i-xxxxxxxx");
System.out.println(instance.getDnsName());

// Enumerate all current instances for this account/region
for (Instance instance : ec2.getInstances()) {
    System.out.println(instance.getDnsName();
}

You can also follow references from one resource to another:

Instance instance = ...;
Subnet subnet = instance.getSubnet();
System.out.println(subnet.getCidrBlock());

for (Volume volume : instance.getVolumes()) {
    System.out.println(volume.getVolumeType() + " : " + volume.getSize());
}

Conclusion

This release is a developer preview, with support for Amazon EC2, AWS Identity and Access Management, and Amazon Glacier. You can browse through the API or go straight to the code. We’ll be adding support for more services and tweaking the API over the next couple months as we move toward GA. We’re very interested to hear your thoughts on the APIs. Please give it a try and let us know what you think on GitHub, Twitter, or here in the comments!