Over a million developers have joined DZone.

Curating Microservices APIs with Cloud Foundry

· Cloud Zone

Download the Essential Cloud Buyer’s Guide to learn important factors to consider before selecting a provider as well as buying criteria to help you make the best decision for your infrastructure needs, brought to you in partnership with Internap.

[This article was written by John Wetherill.]

 In a recent microservices blog I discussed the practice of Creating and Curating Access Libraries, suggesting that "The microservice provider should be responsible for building and stewarding client libraries used to access the service."

And in last week's Get Some REST article I dove into the Cloud Foundry REST API.

Here I'll tie the two together using the Cloud Foundry "cf" CLI client which, while not a library per se, is a perfect illustration of Curating the Cloud Foundry API, and a technique which applies directly to microservices APIs as well.

The Cloud Foundry REST API: Simple but not Easy

The Get Some REST post shows the precise calls required to push an application to Cloud Foundry using the Cloud Foundry REST API. Using this API is flexible, powerful, and relatively straight-forward, but as I mentioned it requires dealing with error handling, parsing responses, acquiring GUIDs for various entities, zipping up application directories, and other low-level work. The API approach is straight-forward, but not as easy as might first seem. There is way too much time spent working on the plumbing, when you really want to be just getting on with deploying your apps.

There is an Easier Way

Instead of all that, how about this:

     cf push

This simple command invokes the "cf" client which takes care of all the nitty gritty details above. It handles errors, deals with the authentication token, parses and interprets responses, creates the zipfile, queries the PaaS for the required information like domain guid. And way more.

All with a single command.


And this exactly is the point. The "cf" command is a perfect example of "stewarding" or "curating" APIs. While the Cloud Foundry APIs are powerful and handy, they're complex to use, and in the absence of the "cf" command anyone wanting to consume this API will have to set about writing their own access utility or library. And maintaining it. And educating other developers about it. And adapting it over time as the underlying API evolves.

The "cf" client provides a standardized wrapper around the various API calls required to perform basic Cloud Foundry operations, like pushing an app.

For most purposes it's preferable to use the cf tool to interact with Cloud Foundry instead of calling the APIs directly. The Cloud Foundry acceptance tests, or CATs do exactly this. Instead of invoking low-level REST calls as might be expected, these tests, which make sure Cloud Foundry is behaving itself, take the much simpler and more maintainable route of directly wrapping the cf command.

This is the Ambassador Pattern

This stewarding approach remeniscent of the Ambassador design pattern.

What does an ambassador do? In real life, an ambassador is an official envoy, or representative, of a country or state, acting as a liaison between that country and a foreign government. The ambassador understands local laws, languages, customs, how to interpret any communications, and how to respond to events and situations that might occur. If a tourist needs help it’s much more efficient to go through the ambassador instead of dealing with the complexities themselves.

Similarly, the cf command acts as an envoy to Cloud Foundry (specifically its REST API) as it understands how to communicate with it, respond to exceptional conditions, interpret responses, and follow the Cloud Foundry customs (aka protocols).

This analogy might be stretching things a bit, but the point is, the library, or tool, takes care of all the details, alleviating the developer from having to worry about it.

Other Cloud Foundry Stewardship Examples

The "cf" command isn't the only access library/utility available for Cloud Foundry. Have a look at the Java cf client, allowing much of the same functionaility through Java.

For example, here are a few lines Java code that invokes the (stewarded) cf Java client to print the name of each space and the organization it's contained in:

for (CloudSpace space : client.getSpaces()) {
   System.out.printf(" %s\t(%s)%n", space.getName(),

Note that the Java client is somewhat lower-level than the cf cli, in that it doesn't provide a single call to push an application. Perhaps a higher-level api is called for to wrap the entire push operation, but on the other hand, perhaps not: it's simple enough to call out to the "cf" cli client directly from Java, and as discussed above, this is the preferred approach.

Another access library worth looking at is ActiveState's cloud-foundry-client-js JavaScript client. This one is handy if you want to manage Cloud Foundry from an application running within the browser. Like the Java client, it doesn't yet have the capability to directly push an application (Pull Requests welcome!), but it does enable access to most Cloud Foundry functionality directly from JavaScript.

All of these: the "cf" command line client, the Java client library, and the JavaScript client, are good illustrations of API stewardship, providing a high-level wrapper around low-level operations that most developers shouldn't have to worry about.

Open Source It!

I recommend that if possible you open source your access library or utility. In addition to the many benefits provided by open sourcing in general, this allows the consumers of the API to see, at the source-code level, directly how the API calls are intended to be made.

This helps to clarify the intent of specification, in cases where the spec might be ambiguous or vague. Effectively you're providing a reference implementation to your consumers, aiding the understanding of the spec, and avoiding fragmentation and misinterpretation.

Advantages to this approach

Stewarding APIs has some powerful advantages, while failing to do so has some drawbacks.

Simply requiring the consumer/customers of your service to build their own access libraries adds burden to the process of adopting your service, a barrier to entry that can be easily avoided by building your own access library or utility.

Additionally, if you don't steward your APIs, you force consumers to write their own access libraries. While doing so, it's possible they might misinterpret your spec, and if their library gains popularity, other consumers will end up relying on the misinterpretations, and fragmentation will occur.

Regardless, it's best to avoid multiple access libraries and tools circulating around the community.


Microservices aren't new, but the use and awareness of microservices have been recently exploding. Naturally, with all this exposure, many microservices-related patterns and practices are evolving rapidly. Stewarding/curating APIs is one example of such a practice, which the cf command (and the stackato CLI too) precisely embodies.

The Cloud Zone is brought to you in partnership with Internap. Read Bare-Metal Cloud 101 to learn about bare-metal cloud and how it has emerged as a way to complement virtualized services.


Published at DZone with permission of John Wetherill, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}