Building great APIs, part I: The gold standard

Back in July, John Musser wrote an excellent post over at ProgrammableWeb on what it takes to build great APIs (also check out his OSCON slides on Slideshare). John boils what’s needed down to five key elements—value, plan and business model, flexibility, good management, and great support.

Together with perhaps just one more–stability (an unreliable API is as good as unusable)–these points arguably should represent an “API Gold Standard” for almost any API program. Getting these right goes a long way to running a great API program and we advise anybody running an API to think about them.

Everything you need to grow your career. With your free Red Hat Developer program membership, unlock our library of cheat sheets and ebooks on next-generation application development. SIGN UP

How to build a great API: 5 steps

Looking back at the 5 (or 6) keys, however, the challenge is how to implement them and succeed in every area? To try to answer this question, we wanted to detail each of the elements a little and uppack what it takes to get them right. This post deals with the first two and we’ll follow up with others. These are our interpretations, but hopefully we’re close to John’s original intent! John Musser’s list is:

Provide a valuable service.

service. Have a plan and a business model .

and a . Make it simple, flexible and easily adopted .

. It should be managed and measured.

and measured. Provide great developer support.

[Credit also goes to Adam Duvander for the post which teased out the 5 items.]

We’ll tackle the first two items on the list. These seem easy to get right, but they are often the most challenging. What makes an API valuable may not be obvious and many APIs don’t quite hit the mark with developers. Further, why would a business model be a critical element? Often business model decisions are delayed or postponed (although this is happening less and less)–but having the business model early can be critical to success.

Provide a valuable service

Justifying an API program is often a challenging sell initially in an organization, and there is usually plenty of discussion around the value proposition of an API to customers/partners and the organization itself. However, this can still be challenging to get right:

It can be hard to establish the true audience of the API: is it developers at hackathons? Technical staff at customer companies? Partners who are expected to become resellers?

There is often a focus on the API itself, rather than what parts of the business the API is driving.

Discussion of “API Metrics” can get in the way of what really matters–developer/customer success.

Looking at such discussions closely, the key thing to identify for an API is generally not the value of the API per se but the value of the effect of the API (e.g., delivering SMS, retrieving valuable content, making a booking, retrieving a record in a SAAS application, getting a package delivered, etc.). That is, it is the organization’s core business which is valuable and the API is a channel into this. So, for example, an API opened by a Pizza company is:

Successful for the company: if it drives more Pizza sales.

and it is:

Successful for customers/partners/developers: if it makes it easy to purchase and deliver Pizza.

Further, for third parties, it may only be successful if:

The purchasing and delivery of Pizza provides revenue flow (either direct or indirect).

In other words, the API often exists to provide new types of access to the existing value an organization provides. Sometimes the advantage of an API can be spectacular and make entirely new business models and products possible (such as for Twitter for example, or Netflix in enabling clients on many platforms), sometimes it is simply a new gateway that extends old channels.

This thinking has a number of important consequences:

API specific metrics such as the number of API calls, number of apps, number of developers etc., while useful for operational management are likely to be a distraction when it comes to measuring the actual value the API is delivering. A particularly chatty API may result in many API Calls, but it rarely leads to a meaningful transaction it is likely failing in its core purpose. When designing an API, it is important to support complete useful use cases where possible. For example, an eCommerce API which permits the retrieval of catalog listings but does not support either actual purchases or embedding of affiliate links to drive web traffic is unlikely to be particularly valuable. The benefit to users of the API needs to be clear and ongoing, as well as most likely built into the API. Whether this takes the form of the user of the API gaining direct benefit (e.g., Great Data/Content or Payment for referrals) or indirect benefit (e.g. visibility in an ecosystem), this needs to be clear from the outset.

A final common misconception is that for an API to be valuable, users must be prepared to pay for it. Also here, this is only true if the API itself is the product, in most cases where API calls are driving some other metric (Pizza Sales, Affiliate referrals etc.) and hence the value of the API to the organization is measured by other metrics and value to users of the API is the effect of the API call, rather than the call itself.

There may be value in the API itself if it makes something which was previously time-consuming or expensive cheaper or something new possible (e.g. importing/exporting information from a SAAS CRM) and customers of an existing product might be willing to “pay” for API usage itself (e.g., if API access is only available on higher tiers of a SAAS service–hence driving upgrades). However, also in these cases, the ultimate value of the API is likely to be to get at the core functionality being delivered and drive more volume, reduce costs for driving that volume, etc.

The good news is that almost any company with an existing product (digital or physical) can likely provide a valuable API since it links to their existing offering and enhances it. As long as the API is structured in such a way that it can genuinely cover meaningful use cases for developers it will deliver value.

Have a plan and a business model

Having a strong plan and business model are two elements of the same question, and in some sense the flipside of the API having value. Starting with the business model, this determines the value of the API to the organization operating it. While there are a wide variety of business models in use for APIs, the question “What Business Model should I adopt for my API” is arguably a misleading one. In fact, the question should more properly instead be:

“What is the API for my Business Model?”

In other words, the question starts with the existing core business the organization has and then extends to how an API can be used to accelerate this or augment it. Sometimes, APIs can lead to entirely new business opportunities – but even here, they generally leverage existing assets or expertise to do so in new ways.

The reasons that business models are important for a great API are:

Determining the business model brings into focus the value of the API to the organization and hence drives the decision to make long term commitments to the API program, without which there is rarely the resource in place to complete many of the other tasks needed for a great API program. Determining the business model also helps define what functionality is needed to enable third parties to actually execute the full cycle of what is needed to actually drive the business model. Lastly, the business model forces the conversation about who retains which parts of the value generated by the API. In other words, what do users of the APIs gain / retain and how does that balance with what the API provider gains?

It is also valuable and important to communicate the business model to customers, partners, etc., since it will help them understand the depth of the commitment to the API as well as the areas which may be “out of bounds” for third parties since they interfere with the key business models in place.

This bridges neatly to the second part of John’s point–the need for plans. While this could have several meanings, the one which stands out is:

the need to have a clear development roadmap, commitment to features/versions and rules of engagement.

A clearly articulated roadmap for the API is invaluable in increasing developer confidence in the API. The plan should be not only technical but also (where possible) contain business elements. Large platforms such as Twitter have now become much more focused on posting such future plans in order to avoid developer anger. A roadmap also engages users of the API in conversation on what might be important to them. Choosing an API to use is a long term commitment – a good roadmap builds confidence that it will be a great relationship.

Up next

In the next post, we’ll cover what it means to make your API flexible and well managed.

Read more