Dr. Dobb's is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

Channels ▼

Web Development

Building Successful Web APIs

As the demand for connectivity between applications, devices, and platforms grows, so too does the need for Web-based interfaces to connect them together. Not too long ago, these interfaces were called "Web services" and they were often the key component of a Service Oriented Architecture (SOA) initiative. But, with increasing frequency, the terms "Web API", "API," and "API program" are now being used instead.

So, what is the difference? For many in the technology field, a Web service implies the usage of the SOAP messaging format, while an API implies that any format other than SOAP will be used for messaging. Further to this, some believe that SOA programs live behind the firewall and support internal connectivity, while API programs are focused on outwards facing integration. The colloquial definitions that have evolved for these terms are interesting to note, but it is important to realize that Web APIs still align with the broader, commonly held definition of an SOA. Ultimately, APIs enable the SOA goals of business and technical alignment, increased component reuse, and a higher level of connectedness.

The key difference between the SOA world and the API domain is philosophical. Architects who talk about SOA are often concerned primarily with the exposure and cataloging of service libraries over the network. Whereas architects who talk about APIs will often emphasize a developer-centric view of integration. It is this focus on the usability of an interface that has radically changed the way Web interfaces are designed and exposed.

Why Does Usability Matter?

The various API business drivers can be reduced into two important goals: the pursuit of growth in API usage and the pursuit of cost reduction in application development. Interest in usability-oriented API design has been fueled by a key realization: Interfaces that are easier to use will help businesses achieve both aims.

Designing for usability is the art of designing products that help users accomplish their own tasks by minimizing the level of user effort required. When given a choice, users prefer products that are easier to use; and in turn, easy to use products improve productivity.

The Nuts and Bolts of Web API Usability

There is a wealth of literature and research available on the design of more-usable interfaces. But the bulk of this material is targeted towards usability design for websites, mobile applications, and physical products; in other words, the products that the average person spends the majority of their time interfacing with. Designing an API for a developer-user who must, in turn, create a software application that can interact with the runtime interface of an API adds a special and important nuance to the usability discussion.

The good news is that even the specific niche of API usability has been well served with guidance from experts. For example, Joshua Bloch's illuminating talk on API design is required viewing and within this publication you can find excellent insight into usability measurement for APIs from Steven Clarke. Even then, the information is not a perfect fit — most of it is geared towards the design of traditional, locally installed APIs. The nature of Web-based interactions are inherently different; nonetheless, this foundation of usability research and existing design advice provides an ideal starting point.

In general, interaction designers must determine how to extend their users' knowledge to use the interface correctly, how to provide the appropriate controls to operate the interface, and how to provide feedback on the result of the interactions. Interaction design pioneer Bill Verplank describes this process as answering the three questions: "How do you do? How do you feel? How do you know?"

If we examine how developers learn, use, and get feedback from Web APIs, we can break down the key interactions into four major categories: discovery, learning, invocation, and analysis.


The first touchpoint for a developer is the discovery of an API that supports a task they want to accomplish.

The method for aiding the discovery of an API often depends on the accessibility of the interface. When an API is created for business partners or for internal use, discovery often occurs through direct and targeted communication from the interface provider. For example, a listing of the APIs that are available and their function may be provided in an email or as part of a contract between two organizations. In some cases, a corporate registry of services might exist to facilitate the internal discovery of an organization's APIs

For public-facing APIs, publishers must provide a means to make developers aware that a programmatic interface exists without having an existing relationship in place. A simple method of advertising the API is to provide links within the organization's primary website to a developer-focused microsite. (In addition, publishers can employ traditional marketing techniques such as email advertisement, conference sponsorship, and hackathon events to increase the likelihood of a discovery interaction and word-of-mouth marketing.)

In some cases, a developer may discover the API before an application function is actually required, possibly leading to the invention of a new application idea based solely on the existence of the API, its underlying function, and the tasks it can facilitate. This type of serendipitous discovery is particularly important when an API has been built to foster innovation.

The key to a successful discovery interaction is to go beyond the minimum requirement of simply communicating the API's existence by helping the prospective developer perceive the value of the product. Good APIs provide straightforward communication of how the interface will provide utility to the developer and support their tasks. For example, users who visit a telephony API page that immediately presents the story of an application using the interface to make a telephone call are likely to quickly grasp the value of the product. This user-focused interaction gives prospective developers an immediate understanding of how the API can help them; and it should lead to higher adoption rates.


Once developers discover an API that helps them achieve their tasks, they must learn the technical details required to actually use it. They need to gain an understanding of the API's architectural style, the names and purposes of entities, and the parameters available to fine-tune results and responses.

In other words, the developer is asking the question "How do I get this API to support the task I am trying to accomplish?" The goal of a highly usable API should be to provide the means to answer this question easily and effectively with appropriate documentation and a suitable interface.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.