Designing Web APIs: Building APIs That Developers Love

by Brenda Jin, Saurabh Sahni, Amir Shevat

Overview

Using a web API to provide services to application developers is one of the more satisfying endeavors that software engineers undertake. But building a popular API with a thriving developer ecosystem is also one of the most challenging. With this practical guide, developers, architects, and tech leads will learn how to navigate complex decisions for designing, scaling, marketing, and evolving interoperable APIs.

Authors Brenda Jin, Saurabh Sahni, and Amir Shevat explain API design theory and provide hands-on exercises for building your web API and managing its operation in production. You’ll also learn how to build and maintain a following of app developers. This book includes expert advice, worksheets, checklists, and case studies from companies including Slack, Stripe, Facebook, Microsoft, Cloudinary, Oracle, and GitHub.

• Get an overview of request-response and event-driven API design paradigms
• Learn best practices for designing an API that meets the needs of your users
• Use a template to create an API design process
• Scale your web API to support a growing number of API calls and use cases
• Regularly adapt the API to reflect changes to your product or business
• Provide developer resources that include API documentation, samples, and tools

Product Details

ISBN-13:	9781492026921
Publisher:	O'Reilly Media, Incorporated
Publication date:	09/27/2018
Pages:	230
Product dimensions:	6.00(w) x 8.80(h) x 0.60(d)

About the Author

Brenda Jin is an entrepreneur and software engineer. As a staff engineer on the Slack developer platform team, she designed, built, and scaled APIs for third-party developers. As a board member and chapter leader for Girl Develop It, Brenda has contributed to numerous open source teaching materials and empowered thousands of women to learn web and software development.

Saurabh Sahni is a staff engineer on the developer platform team at Slack. For the last eight years, he has been building and designing developer platforms and APIs. Prior to working at Slack, Saurabh led a team of engineers responsible for Yahoo Developer Network infrastructure and developer tools, where he helped launch Yahoo Mobile Developer Suite and several APIs.

Amir Shevat is a VP of developer experience at Twitch. He has spent the past 15 years building developer products, APIs, and ecosystems around APIs at Slack, Microsoft, and Google. He is also the author of Designing Bots (O’Reilly).

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

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

A API Design Worksheets 201

Index 207