Amazon AWS SDK for Java: It’s Not Quite There Yet

Amazon released its SDK for Java last month. It’s a complete set of APIs that cover almost all the services from EC2, S3, SQS, RDS to SimpleDB. Overall Amazon has done a consistent job, but the SDK is NOT really object oriented. And that I think is critical for higher development productivity. 

Structure of the SDK

Lost VMs or Containers? Too Many Consoles? Too Slow GUI? Time to learn how to "Google" and manage your VMware and clouds in a fast and secure HTML5 App.

Before explaining why it’s not quite there, let’s take a look at the structure of the API itself. The SDK includes many packages. For each service, you find two or three packages: basic, model, and possibly util package.

In each of the basic packages you can find the two interfaces, and two implementation classes. Let’s pick EC2 as a sample here. The AmazonEC2 and AmazonEC2Async are two interfaces and implemented by AmazonEC2Client and AmazonEC2AsyncClient respectively. More methods are defined in the synchronous than the asynchronous versions with the majority of them overlapping with similar method names.

AllocateAddressResult allocateAddress()
AllocateAddressResult allocateAddress(AllocateAddressRequest allocateAddressRequest)
Future<AllocateAddressResult> allocateAddressAsync(AllocateAddressRequest allocateAddressRequest)

The first two versions wait and get you results upon return. The third version doesn’t wait and gets the result later.

Overall Amazon has done a consistent job all over the different types of services. The consistency is always a great attribute for good API design.

What Should Have Been Done Differently?

If you have done Web Service programming before, you know the SDK is about the same level as the stub generated by a Web Service toolkit in terms of abstraction. With that, you have a fat “client” taking care of everything, including all the possible operations. This is an easy and straight-forward way for the SDK developers to come up with a SDK for the Web Services. But it’s not so easy or straight-forward for the actual SDK users.

As most object-oriented (OO) programmers know, it’s a bad idea to have everything in one fat class. If you have everything in one class, then it’s not really OO programming. That is actually a typical mistake many programmers make while transitioning from a procedural language like C to an object-oriented language like C++.

So what about the classes in the model packages? These classes are really data objects, whose methods are limited to getters and setters. In other words, you can’t do anything meaningful with these data objects. These data objects serve as the parameter and return types for the methods in the two classes: one for synchronous and the other for asynchronous calls. Some of them are actually over-used.

Let’s take a concrete example. The following is a method from AmazonEC2Client class:

public void deleteSubnet(DeleteSubnetRequest deleteSubnetRequest) throws AmazonServiceException, AmazonClientException

The DeleteSubnetRequest is a data object which holds really one string as a subnet ID. It would be better to have the signature as:

void deleteSubnet(String subnetID); 

This is just a minor issue anyway. The bigger issue is that the SDK doesn’t have real Subnet class to which you can add methods like create(), delete(). If yes, you will find the application code can be as straight-forward and easy as this:

Subnet sn =…

Lack of Clear Object Model

The root problem with Amazon’s approach is the lack of a clear object model, which I believe is the core of every successful OO API design.

Nowadays, Web Services and REST are pretty popular. By nature, they are all procedural. Focusing on these can easily shift your attention from the core design to the design of the requests/responses schema, URLs etc. Then you can easily lose the vision of the forest for the individual trees.

The lack of an object model is not a big deal when the API scope is small. When it gets bigger, we will see clear usability issues for the API users.

VMware vSphere API has a great object model as described in its API reference, but gets lost in the Web Services SDK due to the inherent limitation of Web Services. Because the vSphere API is a lot more complicated than Amazon’s SDK, users find it difficult to use. If you’re curious to learn more about how VMware sets out to solve these same problems as Amazon’s latest AWS SDK, first check out the open source vSphere Java API. It re-creates the object model and for first-timers it can be much easier to use than the vSphere Web Services.

For future tricks and tips, feel free to subscribe to this feed, and follow me at Twitter.

This entry was posted in Cloud Computing and tagged , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.

One Comment

  1. Posted April 15, 2010 at 2:12 am | Permalink

    Hi Steve, Nice analysis of the Amazon API’s. I can understand the difficulties involved in using the API’s if the object model is not so clear. I had faced lots of difficulties when I was programming against the vSphere API’s. VI/vSphere SDK API’s are really nasty. But, the open source vSphere Java API’s have addressed most of the complexities found in the vSphere SDK object model. It would be good, if we can get something similar for Amazon SDK also from the open source community.

One Trackback

  • By Why Amazon’s new AWS java sdk sucks on June 11, 2010 at 7:48 pm

    […] the only one screaming over the API. Steve Jin has expressed similar concerns about the API in his DoubleCloud Blog. According to Steve the API lacks consistency, clear object model and the structure of the API is […]

Post a Comment

Your email is never published nor shared. Required fields are marked *


You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.