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 =… sn.delete();
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.