How to define and design cloud APIs, step by step

As enterprises stand up public and private cloud services, they often miss the basics around designing APIs

InfoWorld|Jun 12, 2012

Most cloud computing services are not consumed using visual interfaces; instead, they're consumed through nonvisual interfaces, or APIs. These APIs are typically RESTful services that provide access to fine- or coarse-grained features of the cloud -- for example, infrastructure services such as storage or provisioning, or business services such as updating a purchase order.

Let's say you're building a cloud computing system for an enterprise, and you need to define, design, and implement the services. What are the steps?

First, list all of the system actions, or what those services will do. For example:

Execute credit check

Update customer data

Edit customer data

Remote customer data

Record a sale

There could be hundreds of these or fewer than 10, depending on the complexity of your system.

Second, decompose each service to a functional primitive or break them out as far as you can so that they perform more discrete functions. For example:

Execute credit check

Validate SSN

Submit SSN to credit bureau

Connect to credit bureau

Submit credentials

Invoke credit check

Validate returned score

Return score

The idea is to define each service at its finest-grained level, providing a sound foundation of understanding for the normalization of the services.

Third, place the services into a hierarchy from coarsest-grained to finest-grained. Make sure the services are fully decomposed. Again, for more complex systems, you could be dealing with hundreds of services.

Finally, select the services you should externalize. This means dealing with the coarse-grained versus fine-grained service trade-off. Understand that overly fine-grained services could cause performance and scaling problems, but services that are too coarse-grained don't provide enough degree of control.

The best advice I have, generally speaking, is to stand up the most primitive services you can. This provides more options for those who use the services, as well as the most value for consumers of the services.

It's still more art than science, but as we build more of these, we'll have more best practices to draw from.