James Higginbotham - Designing Great Web APIs: Creating Business Value Through Developer Experience

by James Higginbotham

Copyright 2015 OReilly Media, Inc. All rights reserved.

Printed in the United States of America.

Published by OReilly Media, Inc. , 1005 Gravenstein Highway North, Sebastopol, CA 95472.

OReilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://safaribooksonline.com). For more information, contact our corporate/institutional sales department: 800-998-9938 or corporate@oreilly.com .

• Editor: Allyson MacDonald
• Production Editor: Melanie Yarbrough
• Copyeditor: Amanda Kersey
• Proofreader: Melanie Yarbrough
• Interior Designer: David Futato
• Cover Designer: Randy Comer
• Illustrator: Rebecca Demarest

• July 2015: First Edition

The OReilly logo is a registered trademark of OReilly Media, Inc. Designing Great Web APIs, the cover image, and related trade dress are trademarks of OReilly Media, Inc.

While the publisher and the author have used good faith efforts to ensure that the information and instructions contained in this work are accurate, the publisher and the author disclaim all responsibility for errors or omissions, including without limitation responsibility for damages resulting from the use of or reliance on this work. Use of the information and instructions contained in this work is at your own risk. If any code samples or other technology this work contains or describes is subject to open source licenses or the intellectual property rights of others, it is your responsibility to ensure that your use thereof complies with such licenses and/or rights.

978-1-491-92459-4

[LSI]

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 organizations 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 arent 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. Lets 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 vendorsoften in less than 60 secondsand at a fraction of the cost of purchasing and maintaining a physical server.