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

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?

[ Get a handle on the current state of the cloud with InfoWorld's special report, "Cloud computing in 2012." Download it today! | Stay up on the cloud with InfoWorld's Cloud Computing Report newsletter. ]

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

  1. Execute credit check
  2. Update customer data
  3. Edit customer data
  4. Remote customer data
  5. 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:

  1. Execute credit check
    1. Validate SSN
    2. Submit SSN to credit bureau
      1. Connect to credit bureau
      2. Submit credentials
      3. Invoke credit check
    3. Validate returned score
    4. 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.

This article, "How to define and design cloud APIs, step by step," originally appeared at Read more of David Linthicum's Cloud Computing blog and track the latest developments in cloud computing at For the latest business technology news, follow on Twitter.

Copyright © 2012 IDG Communications, Inc.

How to choose a low-code development platform