Back in May, I took a look at three cloud management platforms:
RightScale, Scalr, and enStratus. Perhaps the biggest surprise was that people from two of those companies—RightScale and Scalr—took note of the article and replied in the comments, offering some clarification on their offerings. (And they were very civil: thank you!) What I'd like to do next is re-visit these platforms, but focus directly on the APIs that the three offer—not so much coding, but a high-level picture of them. How do they stack up? What features do they have? How do they fit with standards? And what can you expect from the long-term?
Wait, What was That About Standards?
The topic of "standards" in cloud APIs is sort of, well, cloudy. There’s at least one online company (hint: it’s named after a really big river) that has spent years designing and enhancing its own API. It's actually a decent API, and as such a common question when reviewing cloud management APIs is whether they support Amazon's API. However, Amazon's API is not a standard supported by any standards organization. There are standards, which I'll get to shortly, but Amazon has no interest in adopting these standards. It’s built a massive infrastructure of APIs across all their products, and those APIs have a lot of common elements. The cloud-management API uses similar structures and formats as those other APIs, and so Amazon has little real reason to change it. But that doesn't mean others can ignore it. On the contrary, a common question that cloud management vendors get asked is if they support Amazon's API—not just for managing Amazon Web Services, but for other cloud platforms as well. In other words, Amazon's API is indeed becoming an ad-hoc standard, whether we like it or not. That said, a couple of other standards have been developed.
Overview of the APIs
One thing these three platforms’ APIs have in common is a reliance on a REST interface; also, they all have authentication. However, I wouldn't consider those "features" so much as "basic requirements of any API that's at least half-baked." So I won't bother evaluating, for example, the authentication. Instead I'll just say that it's there, as it should be. What struck me as more interesting: as I explored these APIs, the more I realized I was essentially being presented with a developer's view into their overall features. While these three products are all about cloud management, looking at their APIs reveals deeper differences. What follows is the developer’s view of each platform’s features through the viewpoint of the APIs.
The RightScale API
The RightScale API is divided into several categories. I won't list them all,
but they can be found here. Everything you’d expect to be included is there, such as Server APIs and Image APIs. To use the RightScale API, you make an authentication call, which sends back a cookie. You save those cookies, and then re-use them in subsequent calls. (For example, with curl, you use the -b option.) To make a call, you build up your URLs from left to right, as is common with a REST interface. For example, if you want to start a server, your URL looks like this:
https://my.rightscale.com/api/acct/1111/servers/2222/start
Where 1111 is the account number, and 2222 is the server number. The API uses the standard parameter approach for REST calls (such as -d parameter in curl), but the format is unusual. Here's part of an example that I pulled from the examples in the documentation (
found here):
POST -d permission[user_href]=/api/users/11 -d permission[role_title]=observer https://my.rightscale.com/api/permissions
The parameters take the format of a name, followed by a "subname" in brackets. No big deal; still easy. The RightScale API also lets you return data in either JSON or XML, which is a nice feature. But the API doesn't seem to be complete. You still have to do a lot through their control panel. The general idea is that you're apparently writing supportive scripts that support your work, rather than all-out replacements for the control panel. If I were to give an award for worst API documentation, it would be to RightScale. And that's surprising for two reasons: First, the rest of their documentation is really good. They have lots of examples how to use the features of their products, and they're well written. And second, RightScale has offered a strong developer focus for some time. So I don't know why their API documentation is, frankly, pathetic. (Actually, I do know why it sucks.
The main index page “API 1.5 Reference” has the word "generated" at the bottom, followed by a date. The documentation was probably pulled—or
sucked—out of the API itself.) They do have some examples, though, which should help you get going. There are more examples for the 1.0 API, and only a few for the 1.5 API. But they are actively working on a 2.0 API that will support Amazon as well as the other clouds they support; hopefully that API will have better documentation and more examples. Although the direct API documentation isn't very good, RightScale has really good support for third-party development platforms.
There's full support for Chef and, with that, strong support for using Chef with Ruby.
The enStratus API
If you look at sheer size, there is no question that the enStratus API takes the lead. The API reference document is an entire book clocking in at 365 pages. I didn't take the time to count the API calls (I don't have
that much time on my hands), but I can say that the API calls are organized into eight separate groups: Admin, Analytics, Automation, Finance, Geography, Infrastructure, Network, and Platform. At the other extreme is Scalr, which only has about 28 API calls. What does that tell us? It doesn't say that EnStratus is necessarily "better" than Scalr. Rather, it tells us that EnStratus has a broader range of features. Whether you actually need all those features is up to you. And if you only need a subset of those features, and Sclar happens to offer those same features, then Scalr might be the better fit for you. But before talking too much about Scalr, let's look more closely at the enStratus API. The enStratus API follows a rather strict REST model, making use of the GET, POST, PUT, and DELETE verbs. This should be obvious to REST programmers, but GET retrieves data, POST modifies data, PUT creates data, and DELETE, of course, deletes data. The URLs are constructed as endpoint/version/namespace/resource. The GET queries also support pagination in the responses. The POST and PUT actions allows data to be sent either as XML or JSON. You can get data back either as XML or JSON; to do so you include an Accept header, passing either "application/xml" or "application/json.” You will then get back any one of the standard response codes; for example, 200, as usual, means success, 403 means unauthorized, and so on. (These are all documented in extreme detail in the documentation book.) In order to authenticate your requests, you use a method that's a bit stricter than RightScale's cookie-based approach. All calls must be signed using an SHA256 signature via a secret key. The call then includes the public API key along with the signature, and even a timestamp. If you've worked with Amazon's various APIs (not just their AWS but other products) you'll notice that this is a similar approach, including the use of a timestamp to help prevent replay attacks. Calls made outside of a ten-minute boundary on either side of the timestamp are rejected. (The reason for either side is probably to accommodate those situations where the clock on the calling server isn't quite correct.) This still allows a request to happen twice if it's within 10 minutes, so there's a further option in the form of a header that does not allow the call to be repeated. Because the system is true to the REST form, you execute your REST verbs against objects. For example, one such object is BillingCode. What is BillingCode? Well, the documentation defines it as, "A billing code is a budget item with optional hard and soft quotas against which cloud resources may be provisioned and tracked." What does that have to do with managing a cloud, such as allocating instances and so on? Lots, actually. EnStratus includes full features for managing private clouds that support customers. As such, there's an entire API devoted to account management. This part of the API includes objects such as Account, ApiKey, Customer, Role, and User. Back to the REST concept: the calls operate against these objects. Here's an example from the docs for adding data to a BillingCode object. Since you're creating one, you use the PUT verb. And then you can either pass the data as JSON or XML. This example uses XML:
PUT /api/enstratus/2012-02-29/admin/BillingCode/50531 HTTP/1.1 User-agent: enStratus Test Case Accept: application/xml x-esauth-access: FMKPVBVBCKUZJETXXRVP x-esauth-signature: XZwrqInP33DPBuG2rUv2uJ5xJBhZb1e+cZjKNchiffk= x-esauth-timestamp: 1333599504519 x-es-details: basic x-es-with-perms: false <setQuota> <billingCodes> <billingCode billingCodeId="50531"> <softQuota currency="USD">200.75</softQuota> </billingCode> </billingCodes> </setQuota>
You can see how this call's URL drills down to an object of type BillingCode, and then to the actual BillingCode object with ID 50531. The headers include the signature and the timestamp. And the data itself is XML that sets a softQuote object of current USD and amount 200.75. The entire enStratus API is very straightforward and complete, and the documentation is outstanding. As for Chef support, that's there too.
The Scalr API
Scalr includes some powerful features for managing DNS zone files, and their API reflects these features. There are also some Scalr features and APIs for configuring apache HTTP servers, although this seems to be limited to only creating and listing Apache virtual hosts. Scalr also includes APIs for managing farms (listing, creating, getting details, launching, terminating), managing servers (listing, creating, launching, terminating, rebooting), and running scripts on servers as well as listing scripts and getting details of scripts. The Scalr API isn't quite as strict to the REST concept as the enStratus API. For example, there are two separate calls for creating and listing Apache virtual hosts, and the calls don't seem to take into consideration the verbs. (Personally this doesn't bother me, but I know a lot of REST purists who won't be happy about that.) Before you can make a call in the Scalr API, you need to sign your requests, just as with enStratus. In fact, I mentioned earlier the Amazon APIs use signing; Scalr uses the same approach as Amazon (and even gives credit to Amazon in one of the examples). The examples don't use curl, which I think is fine because my experience is that most of us writing these management apps don't actually use curl except for testing. Instead examples are given in PHP, Java, and Perl. Included inside those samples is the code for signing the calls and adding the signature on to the call. Here's such an example; this is a request for launching a server farm:
https://api.scalr.net/?Action=FarmLaunch &FarmID=123 &Version=2.0.0 &KeyID=<Your Scalr API Key ID> &TimeStamp=2009-06-19T05%3A13%3A00.000Z &Signature=...
As you can see, the data is passed primarily as get parameters; again, this is very similar to Amazon's approach. The URL doesn't drill down in the strict RESTful sense as enStratus does. (But I suppose if Amazon doesn't want to do strict RESTful APIs, then Amazon ain't gonna do strict RESTful APIs. And the world, including Scalr, will follow.) Instead of drilling down, the action is provided as a parameter called Action. Additional parameters are then included, and finally the signature is tacked on programmatically. But this whole call is usually put together programmatically. In the PHP examples, the parameters are all placed into an array:
$params = array('Action' => 'FarmsList', ...etc.
The parameters are gathered into a string, a signature is calculated, and then that signature is added into the parameter array itself. The call is then made via file_get_contents. The general feeling I get from Scalr's API (and, indeed its overall feature set) is that the designers of Scalr took what they thought were the most important features and implemented them, all without going crazy adding a million features you may or may not need, especially when compared to EnStratus and RightScale. Also, remember that I'm only covering the API here. There are more features in Scalr beyond what the API covers, but it's still lean. Then add to that the fact that it's open source, and what you get is a system for the budget-minded people who don't need loads of features. But it's clearly not limited to just that group of people. I've heard stories of people using it to manage dozen or hundreds of servers. The documentation on Scalr—not just for the APIs, but the whole thing—is very nice. They found some pretty good writers to put it together.
Conclusions
Before we can draw any conclusions, we need to first determine what your goals are. Are you looking at the APIs to decide which platform is best for you? Or are you looking at overall features and you want to also factor in the API? Further, how will you be using the API? Will you be writing complex applications and rolling your own entire management system, or will you be using the API only sparingly? Clearly, enStratus has the most complete API. But it's also pretty complex, and you have to make sure you're willing to write code that strictly adheres to a RESTFul interface. (You can't just call file_get_contents.) Or if you need to do more than just manage servers and manage accounts, enStratus can do it. If you're looking for a simple API wrapped around some pretty complete features, then Scalr is a good way to go. Now what about RightScale? RightScale seems to fit right in the middle. The API is definitely bigger and more broad than Scalr; it's a bit more RESTful but not quite as strict. From there, it's up to you to go through your requirements and factor in the APIs of these three products.
Image: Dmitriy Shironosov/Shutterstock.com