Table Of ContentEarly praise for Design and Build Great Web APIs
Written in a lively and entertaining style, Design and Build Great Web APIs is a
truly comprehensive journey through the development of high-quality APIs: it’s
accessible for those who are new to the field while also providing food for thought
for the more experienced. The worked examples, alongside chapter-by-chapter
exercises, provide excellent hands-on learning, which is unusual for books in the
API field.
➤ Fiona McLoughlin
API Design and Governance, HSBC Global Services
Mike Amundsen’s latest book is a hands-on text that makes building web APIs
accessible to new developers while reminding more experienced ones of the simple
concepts that drive good API design. I’m recommending this book to every devel-
oper or technical product manager who joins my team.
➤ Shelby Switzer
Digital Service Expert
This is a practical guide for anyone developing APIs. My favorite part about this
book is that the design principles and approaches are universally applicable, no
matter what API style or protocol you choose.
➤ Matt McLarty
Global Leader of API Strategy, MuleSoft, a Salesforce Company
Design and Build Great Web APIs is a comprehensive resource that will teach you
the methods to create and represent your APIs and transfer them into production
with modern techniques and clear definitions.
➤ Michael Nygard
Author of Release It! Design and Deploy Production-Ready Software,
Second Edition
If you are new to API development, Mike will propel you forward in understanding
and practical knowledge that those of us in the API space spent years acquiring
through trial and error. If you are an API veteran, you’ll learn new things and gain
broader understanding.
➤ Mark W. Foster
Principal Software Engineer
This book has everything you need to develop and maintain web APIs. It’s valuable
for anyone getting started, but it also has a lot of information that’s helpful for
veteran developers.
➤ Nick McGinness
Software Engineer
A clear and compassionate guide to both technical and business aspects of API
design. You’re in good hands.
➤ Leonard Richardson
Co-author of RESTful Web APIs
Design and Build Great Web APIs will help you do exactly that. Mike Amundsen
shares his knowledge of designing APIs in an approachable, logical, and manage-
able way that anyone involved in API design and development can benefit from.
➤ Ashish Dixit
Senior Software Engineer, Fastly, Inc.
We've left this page blank to
make the page numbers the
same in the electronic and
paper books.
We tried just leaving it out,
but then people wrote us to
ask about the missing pages.
Anyway, Eddy the Gerbil
wanted to say “hello.”
Design and Build Great Web APIs
Robust, Reliable, and Resilient
Mike Amundsen
The Pragmatic Bookshelf
Raleigh, North Carolina
Many of the designations used by manufacturers and sellers to distinguish their products
are claimed as trademarks. Where those designations appear in this book, and The Pragmatic
Programmers, LLC was aware of a trademark claim, the designations have been printed in
initial capital letters or in all capitals. The Pragmatic Starter Kit, The Pragmatic Programmer,
Pragmatic Programming, Pragmatic Bookshelf, PragProg and the linking g device are trade-
marks of The Pragmatic Programmers, LLC.
Every precaution was taken in the preparation of this book. However, the publisher assumes
no responsibility for errors or omissions, or for damages that may result from the use of
information (including program listings) contained herein.
Our Pragmatic books, screencasts, and audio books can help you and your team create
better software and have more fun. Visit us at https://pragprog.com.
The team that produced this book includes:
Publisher: Andy Hunt
VP of Operations: Janet Furlow
Executive Editor: Dave Rankin
Copy Editor: Molly McBeath
Indexing: Potomac Indexing, LLC
Layout: Gilson Graphics
For sales, volume licensing, and support, please contact [email protected].
For international rights, please contact [email protected].
Copyright © 2020 The Pragmatic Programmers, LLC.
All rights reserved. No part of this publication may be reproduced, stored in a retrieval system,
or transmitted, in any form, or by any means, electronic, mechanical, photocopying, recording,
or otherwise, without the prior consent of the publisher.
ISBN-13: 978-1-68050-680-8
Encoded using the finest acid-free high-entropy binary digits.
Book version: P1.0—October 2020
Contents
Acknowledgments . . . . . . . . . . . xi
Preface . . . . . . . . . . . . . . xiii
Part I — Getting Started
1. Getting Started with API First . . . . . . . . . 3
Adopting the API-First Principle 3
Exploring APIs with curl 7
What’s Next? 18
Chapter Exercise 19
2. Understanding HTTP, REST, and APIs . . . . . . 21
Understanding Web API Protocols, Practices, and Styles 21
Managing Files with Git 31
What’s Next? 40
Chapter Exercise 41
Part II — The Design Phase
3. Modeling APIs . . . . . . . . . . . . 45
Understanding Norman’s Action Lifecycle 45
Modeling Our Onboarding API Lifecycle 50
Managing Your Project with npm 59
What’s Next? 68
Chapter Exercise 69
4. Designing APIs . . . . . . . . . . . . 71
The Power of Design 71
The API Design Method 75
Identifying Your API Descriptors 76
Contents • viii
Creating Your Sequence Diagram 80
What’s Next? 90
Chapter Exercise 90
5. Describing APIs . . . . . . . . . . . . 93
Learning the Role of Description Formats 93
Describing Your API with ALPS 98
Updating Your API Project 107
What’s Next? 108
Chapter Exercise 109
Part III — The Build Phase
6. Sketching APIs . . . . . . . . . . . . 113
Learning from Frank Gehry’s Sketches 113
API Sketching Example 115
The Advantages of Sketching 118
Sketching APIs with Apiary Blueprint 118
API Sketching Tips and Tricks 125
What’s Next? 128
Chapter Exercise 128
7. Prototyping APIs . . . . . . . . . . . 131
What Is an API Prototype? 131
API Prototyping with OpenAPI 134
Translating Your API Design into HTTP 136
Creating Your OpenAPI Document with SwaggerHub 138
Saving and Exporting Your API 149
Mocking Your API 151
Generating Your API Documentation 153
What’s Next? 155
Chapter Exercise 155
8. Building APIs . . . . . . . . . . . . 157
Defining the API Build Process 158
Relying on a Repeatable Process 158
Coding APIs with NodeJS and DARRT 159
Putting It All Together 173
What’s Next? 177
Chapter Exercise 177
