Cloud Computing, software oriented architecture (SOA) and web 2.0 have different purposes, although all of them use an application programming interface (API) to accomplish their objectives. This affects the way the APIs are designed, but not necessarily their implementation.
Best Practice: how to define, design and implement an API
As a provider, should you use a SOAP based API for your cloud? It is an important decision because SOAP is closely associated with enterprise and it has the stigma of SOA's failure. It can drive the web 2.0 projects away from your service, and the same may happen with the enterprise customers if you provide a RESTful JSON based API instead of a strictly defined standard such as SOAP.
It's not a surprise then that Amazon S3 provides a REST-type API and a SOAP API, although back in 2006 when the Cloud storage service was released usage was about 80% for REST and only 20% for the SOAP interface.
When we started to design our public API at Memset, we wanted to keep it as simple as possible so our customers could use it from the command line on their servers with stock tools such as cURL or wget and no programming knowledge.
We believe the best option for this is to use a REST-alike interface with JSON over HTTPS. It's simple, relies on a well known and secure protocol (HTTPS) and, thanks to JSON, it provides a convenient way of structuring the API responses.
However we wanted our customers to be able to perform complex operations from their own applications too. Unfortunately a RESTful API is too close to plain HTTP and it needs an abstraction layer to be useful up to the level we wanted to support.
Based on these requirements, the best solution was to provide two different interfaces for the same API methods: JSON over HTTPS and a high level interface using XML-RPC protocol over HTTPS.
XML-RPC is a remote procedure call (RPC) protocol that has been around for 14 years now and is very well supported, with open source libraries available for almost all programming languages, so we don't need to provide specific support besides documenting the API methods.
Why Open Source?
If you want your customers to build their business on top of your infrastructure, and that's what Cloud is about, you must be as open as possible. Relying on open protocols and widely used open standards is very important because it makes it easier for your customers to start using your technology.
Memset is a strong supporter of open source and we avoid any "black box" projects in our toolbox and our infrastructure is built using a mixture of custom development and open source projects. It makes sense our API supports that philosophy.
What are the main considerations when developing and designing a Cloud API?
One of our main considerations when designing the API was accessibility: it must be easy to use, even if you don't know anything about programming.
Documentation is very important, and we have put extra care so the method hierarchy makes sense and the methods are well documented. We include examples in seven different programming languages, and we distribute an open source interactive shell to explore the API.
Once the API is easy to use, you must provide a secure framework: how do you handle authentication and authorisation when your API can be used from a potentially insecure script in a server? Sadly using a secure transport (HTTPS) is not enough.
This is why we implemented scoped API keys, so a customer can create as many keys as he want restricting their scope to certain services and/or methods. In that way you can have an API key that is valid to reboot a specific server only, minimising the impact if the key gets compromised.
Finally the question you must be able to answer when designing an API is: could I use the API myself? If you can manage your own infrastructure using the API you're providing to your customers, you're on the right path.