Designing Great Web APIs

Chapter 1. The Business of APIs

Web APIs are everywhere. Just browse any technology news website and you are likely to read something about the latest product launching an open API. Companies are making huge investments in providing APIs to internal developers, partner organizations, and public developers. APIs that were once used to solve integration problems have now become the backbone for an organization’s digital strategy.

What Are APIs?

An API, or application programming interface, is the specification of how one piece of software can interact with another. It is best thought of as a contract between software and the developers using it.

As an example, if you provide a display message to the confirm dialog API inside a browser, then the browser will display the message inside of a pop-up dialog and offer OK/Cancel buttons to proceed when the user presses OK, or cancel if the user presses Cancel:

if (window.confirm("Do you really want to leave?")) {
  window.open("done.html", "Thanks for visiting!");
}

Using the preceding window.confirm() API results in a browser confirmation dialog:

Traditionally, APIs have always been part of software development. Operating systems such as Microsoft Windows and Mac OS or mobile platforms such as iOS and Android offer APIs that allow developers to build software on top of their platform. Developers depend upon these APIs to exist, operate as expected, and not break their contract without sufficient notice.

As software has moved from a focus on desktop and web to mobile computing, there has been an increased demand for web APIs. These modern web APIs aren’t just built to integrate systems within an organization. Instead, they allow businesses to share business capabilities and data, build community, and foster innovation. This has led to the rise of the API economy.

The Rise of the API Economy

The API economy is a term that was coined to describe the growth of revenue and brand engagement as a result of offering public APIs for developers. Let’s examine the reasons that gave rise to the API economy.

Reason #1 – Higher Demand

Historically, APIs were used to integrate different software systems or even different organizations. Web APIs are now in high demand due to three key factors: the modern browser, mobile devices, and the Internet of Things.

Years ago, modern browsers were limited to displaying content and limited scripting capabilities using JavaScript. Modern browsers have moved beyond this, allowing rich web applications to be built using a combination of HTML, CSS, and modern JavaScript frameworks. As a result, we no longer require servers to generate complete web pages. Instead, JavaScript frameworks request data from one or more web APIs, dynamically changing what the user sees and the actions they can perform.

In addition to modern browsers, there has been explosive growth in mobile devices such as phones and tablets. These devices have access to the Internet from most locations and offer GPS location and app-store distribution. Applications no longer have to be web pages in a browser. Instead, they can use APIs to access data and business logic to get things done.

Finally, the Internet of Things (IoT) is moving the world of devices, previously requiring human intervention, into autonomous replacements that combine the physical world with the world of software. As a result, APIs enable IoT devices to broadcast their telemetry data and receive commands from other systems. IoT is an emerging domain that will greatly benefit from integrating and providing APIs.

Reason #2 – Simplicity

Historically, enterprises adopted technologies such as SOAP or XML-RPC to integrate applications internally and between partner organizations. These technologies often required additional standards and specifications on top of transport protocols such as HTTP. However, these technologies are meant for systems integration where rigid specifications are most important.

Modern web APIs abandon the need for these complex standards, instead choosing a simpler solution. They encourage the use of HTTP, the protocol that powers the Web, as the foundation for APIs. The HTTP specification was designed to support a robust set of request verbs (i.e., what you want to do) and response codes (i.e., the result of the request). The philosophy for web APIs is to avoid additional standards and specifications, instead choosing to use the HTTP standard to define how web APIs operate.

By choosing HTTP as the only standard, any application or device can consume a web API using built-in programming libraries. No longer are expensive software solutions and complicated standards required. This means easy integration for any device: mobile phones, browsers, or even cars with mobile network access can consume web APIs.

Reason #3 –Lower Cost

By choosing HTTP for our APIs, companies can avoid allocating large budgets of time and money to learn, build, and maintain complex software-technology stacks. Instead, built-in and open source programming libraries can be used to create and consume a variety of web APIs.

With the introduction of cloud computing, any business or individual developer can provision a complete data center on a credit card. No longer do you have to purchase tens of thousands of dollars of equipment, wait for it to be shipped to a data center, physically install it, and configure it for use. Now anyone can provision a server from one of multiple cloud vendors—often in less than 60 seconds—and at a fraction of the cost of purchasing and maintaining a physical server.

Reason #4 – New Business Models

As software moved from installed, on-premise solutions to Software-as-a-Service (SaaS) products, web APIs became more popular for accessing data and automating integration. Eventually, companies offering SaaS products realized that their APIs were just as valuable as the product itself. They could even be productized independently from the core SaaS offering.

As the API economy emerged, new API business models were identified, including free, developer pays, developer gets paid, indirect, and internal. The free or developer pays subscription models are the most common, although the other models are used with specific strategies in mind.

As a result of the API economy, businesses must market APIs to developers directly to gain traction and generate revenue. This places heavier emphasis on great API design to gain developer acceptance, whether the API will be open to the public or only used internally.

Business Advantages of Web APIs

Today, companies are using web APIs to transform their businesses as well. Netflix uses APIs to enable streaming across more than 200 different devices. Over half of eBay’s listings are posted using its API. Best Buy has used APIs to transform itself in the face of online retail competitors. Walgreens has wrapped every corner store with an API to enable local photo printing and other services, all powered by developers.

Businesses are using Web APIs to increase revenue, improve innovation, and reduce their time-to-market through two strategies: consuming APIs from others and exposing their own APIs for internal and external developers.

Consuming APIs from Others

APIs allow businesses to leverage the hard work of other developers. Rather than building every feature in-house, teams can leverage third-party APIs to add new functionality and focus on the aspects of the solution that are unique. For some solutions, this may result in building an application entirely from third-party APIs, with little or no custom development.

When selecting a third-party API for integration, it is important to consider the API provider’s strengths and weaknesses. An API provider needs to have a business model that indicates longevity, to prevent the API from being shut down in the future. It should also have a documented process for upgrading and versioning APIs to prevent breaking your existing applications. Finally, it should invest in great documentation to help your developers, while offering support processes when your developers are experiencing difficulties. If care is not taken when selecting an API provider, the result can be worse than building the feature in-house.

Exposing APIs to Other Developers

While many organizations are resistant to building and exposing APIs to partner or public developers, there are several advantages for doing so:

• APIs allow your customers to innovate without depending on your team. This allows them to customize your solution as they wish, a requirement that is often necessary for mid and large-size organizations.

• APIs often result in additional revenue streams by productizing your business capabilities as a service. For product companies, this may be a necessary step to closing sales (or accelerating the close).

• APIs create partner networks, allowing third-parties to sell your software by offering API-based integration to your solution.

Building web APIs are often considered an integration problem best left to the technology team. However, web APIs are more than just a technology solution: they reach to the heart of the business. Everything an API offers (and doesn’t offer) speaks volumes about what an organization most cares about. This means that organizations need to view web APIs as a business asset, not just a technology solution. An organization’s API provides a view into what the business truly values; the quality of its API design provides a view into how the business truly values developers.

Web API Development versus Traditional Software

Unlike past trends that market to business leaders, APIs market directly to developers. And developers demand more than just a marketing website that lists the features in bullet points. They demand an intuitive, easy-to-use API that can quickly be integrated into their next project.

This requirement, called “developer experience,” is transforming the way that APIs are designed. Organizations can no longer bolt on an API as an afterthought and force developers to use it. Instead, entire markets are emerging where APIs compete for the attention of developers.

This means that an API that solves developer problems and comes with a great design will have a greater chance of winning their attention. Your web API design is a competitive advantage.

With all of this in mind, the remainder of this book provides insights into designing a great API that results in creating value for your business.