Designing Web APIs: Building APIs That Developers Love

232 Pages·2018·9.137 MB·English

by  Brenda Jin, Saurabh Sahni, Amir Shevat

Designing
Web APIs
BUILDING APIS THAT DEVELOPERS LOVE
Brenda Jin,
Saurabh Sahni &
Amir Shevat

Designing Web APIs
Building APIs That Developers Love
Brenda Jin, Saurabh Sahni,
and Amir Shevat
BBeeiijjiinngg BBoossttoonn FFaarrnnhhaamm SSeebbaassttooppooll TTookkyyoo
Designing Web APIs
by Brenda Jin, Saurabh Sahni, and Amir Shevat
Copyright © 2018 Brenda Jin, Saurabh Sahni, and Amir Shevat. All rights reserved.
Printed in the United States of America.
Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA
95472.
O’Reilly books may be purchased for educational, business, or sales promotional use.
Online editions are also available for most titles (http://oreilly.com/safari). For more
information, contact our corporate/institutional sales department: 800-998-9938 or
[email protected].
Acquisitions Editor: Mary Treseler Indexer: Ellen Troutman
Development Editor: Angela Rufino Interior Designer: David Futato
Production Editor: Justin Billing Cover Designer: Karen Montgomery
Copyeditor: Octal Publishing, Inc. Illustrator: Rebecca Demarest
Proofreader: Rachel Head
September 2018: First Edition
Revision History for the First Edition
2018-08-28: First Release
See http://oreilly.com/catalog/errata.csp?isbn=9781492026921 for release details.
The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Designing Web
APIs, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc.
The views expressed in this work are those of the authors, and do not represent the
publisher’s views. While the publisher and the authors have used good faith efforts
to ensure that the information and instructions contained in this work are accurate,
the publisher and the authors 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-492-02692-1
[LSI]
Table of Contents
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
1. What’s an API?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Why Do We Need APIs? 2
Who Are Our Users? 2
The Business Case for APIs 3
What Makes an API Great? 7
Closing Thoughts 8
2. API Paradigms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Request–Response APIs 9
Event-Driven APIs 19
Closing Thoughts 25
3. API Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Authentication and Authorization 27
OAuth 28
WebHooks Security 42
Closing Thoughts 46
4. Design Best Practices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Designing for Real-Life Use Cases 47
Designing for a Great Developer Experience 48
Closing Thoughts 59
5. Design in Practice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Scenario 1 62
iii
Scenario 2 72
Closing Thoughts 79
6. Scaling APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Scaling Throughput 82
Evolving Your API Design 90
Paginating APIs 97
Rate-Limiting APIs 102
Developer SDKs 114
Closing Thoughts 116
7. Managing Change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Toward Consistency 117
Backward Compatibility 127
Planning for and Communicating Change 128
Closing Thoughts 142
8. Building a Developer Ecosystem Strategy. . . . . . . . . . . . . . . . . . . . . 143
Developers, Developers, Developers 144
Building a Developer Strategy 147
Deriving Measurements 160
Closing Thoughts 161
9. Developer Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
API Documentation 163
Samples and Snippets 172
Software Development Kits and Frameworks 175
Development Tools 179
Rich Media 180
Community Contribution 182
Closing Thoughts 183
10. Developer Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Defining Your Developer Programs 185
Deep Developer Programs 187
Broad Developer Programs 192
Measuring Developer Programs 197
Closing Thoughts 198
11. Conclusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
iv | Table of Contents
A. API Design Worksheets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Table of Contents | v

Preface
Building a popular developer platform with an API that is used by
millions of developers is one of the most challenging and exciting
endeavors you can undertake in your software career. In this book,
you’ll learn how to do that.
APIs are at the core of modern software development. They tackle a
basic developer challenge: how can I, as a software engineer, expose
the code I’ve written to other developers to use and innovate with?
Building software in the modern world is very much like building
with LEGO bricks. As a developer you have access to a vast set of
APIs that expose services such as payments, communication,
authorization and authentication, and so forth. When building new
software, your job as a software engineer is to use these APIs to
compose your new product, reusing code that others built in order
to save time and avoid reinventing the wheel.
Many software engineers who enjoyed playing with LEGOs as kids
still love to play with them today. And who wouldn’t? It’s fun, and
you get to build useful stuff with awesome colorful pieces that con‐
nect to one another seamlessly. But what if you could build the
LEGO itself? Wouldn’t it be great if you could invent not only new
LEGO kits, but also the LEGO parts themselves, and let others inno‐
vate with them? When building your own API, you are in effect cre‐
ating your own LEGO parts for other developers to use.
APIs are not a new concept in computer science—in the ’60s, devel‐
opers began to build standard libraries for the first procedural lan‐
guages and share these with other developers. These developers
could use the standard functionality of these libraries without know‐
ing their internal code.
vii
Then, in the ’70s and ’80s, with the emergence of network-
connected computers, came the first network APIs that exposed
services developers could consume through Remote Procedure Calls
(RPCs). With RPCs, developers could expose their functionality
over the network and call remote libraries as if they were local. Pro‐
gramming languages like Java provided further abstraction and
complexity, with messaging middleware servers that listed and orch‐
estrated these remote services.
During the ’90s, with the emergence of the internet, many compa‐
nies wanted to standardize the way we build and expose APIs.
Standards such as the Common Object Request Broker Architecture
(CORBA), the Component Object Model (COM) and Distributed
Component Object Model (DCOM) by Microsoft, and many others
sought to become the de facto way to expose services over the web.
The problem was that most of these standards were complex to
manage, mandated similar programming languages on both sides of
the network, and sometimes required the local installation of part of
the remote service (commonly called a _stub_) in order to access it.
It was a mess; the dream of interoperability soon became a night‐
mare of configurations and constraints.
In the late ’90s and early ’00s came more open and standard ways of
accessing remote services over the web (web APIs). First with the
Simple Object Access Protocol (SOAP) and Extensible Markup Lan‐
guage (XML), and then with Representative State Transfer (REST)
and JavaScript Object Notation (JSON), accessing services became
easier and more standardized without dependencies on client-side
code or programming language. We cover the more popular and
useful of these methods in this book.
One by one, every tech company began exposing useful services
through APIs—from the early days of the Amazon Affiliate API
(2002), to the Flickr API (2004), the Google Maps API (2005), and
the Yahoo! Pipes API (2007), there are now thousands of APIs
exposing every service imaginable, from image manipulation to arti‐
ficial intelligence. Developers can call these and create new products
that are a composition of multiple APIs, just like building with
LEGO bricks.
Although APIs have become a commodity and using them an easy
task, building an API is still an art form. Do not take this challenge
lightly; building a solid API is not easy. APIs should be brilliantly
viii | Preface