Designing Web APIs: Building APIs That Developers Love

Cover......Page 0
Copyright......Page 4
Table of Contents......Page 5
Preface......Page 9
 How This Book Is Organized......Page 11
 Conventions Used in This Book......Page 12
 How to Contact Us......Page 13
 Acknowledgments......Page 14
Chapter 1. What’s an API?......Page 15
 Who Are Our Users?......Page 16
 The Business Case for APIs......Page 17
  APIs for Internal Developers First, External Developers Second......Page 18
  APIs for External Developers First, Internal Developers Second......Page 19
  APIs as the Product......Page 20
 What Makes an API Great?......Page 21
 Closing Thoughts......Page 22
 Request–Response APIs......Page 23
  Representational State Transfer......Page 24
  Remote Procedure Call......Page 27
  GraphQL......Page 28
  WebHooks......Page 33
  WebSockets......Page 36
  HTTP Streaming......Page 37
 Closing Thoughts......Page 39
 Authentication and Authorization......Page 41
 OAuth......Page 42
  Token Generation......Page 44
  Scopes......Page 46
  Token and Scope Validation......Page 48
  Token Expiry and Refresh Tokens......Page 49
  Listing and Revoking Authorizations......Page 51
  OAuth Best Practices......Page 52
  Verification Tokens......Page 56
  Request Signing and WebHook Signatures......Page 57
  Thin Payloads and API Retrieval......Page 58
  WebHook Security Best Practices......Page 59
 Closing Thoughts......Page 60
 Designing for Real-Life Use Cases......Page 61
  Make It Fast and Easy to Get Started......Page 62
  Work Toward Consistency......Page 64
  Make Troubleshooting Easy......Page 66
  Make Your API Extensible......Page 70
 Closing Thoughts......Page 73
Chapter 5. Design in Practice......Page 75
  Define Business Objectives......Page 76
  Outline Key User Stories......Page 78
  Select Technology Architecture......Page 79
  Write an API Specification......Page 82
 Scenario 2......Page 86
  Outline Key User Stories......Page 87
  Write an API Specification......Page 88
  Validate Your Decisions......Page 91
 Closing Thoughts......Page 93
Chapter 6. Scaling APIs......Page 95
  Finding the Bottlenecks......Page 96
  Adding Computing Resources......Page 99
  Database Indexes......Page 100
  Caching......Page 101
  Scaling Throughput Best Practices......Page 103
  Introducing New Data Access Patterns......Page 104
  Adding New API Methods......Page 106
  Adding New Options to Filter Results......Page 109
  Offset-Based Pagination......Page 111
  Cursor-Based Pagination......Page 113
 Rate-Limiting APIs......Page 116
  What Is Rate-Limiting?......Page 117
  Implementation Strategies......Page 119
  Rate Limits and Developers......Page 124
  Rate-Limiting Best Practices......Page 126
  Using gzip......Page 128
  SDK Best Practices......Page 129
 Closing Thoughts......Page 130
 Toward Consistency......Page 131
  Automated Testing......Page 134
  API description languages......Page 136
 Backward Compatibility......Page 141
 Planning for and Communicating Change......Page 142
  Communication Plan......Page 143
  Adding......Page 145
  Removing......Page 146
  Versioning......Page 147
 Closing Thoughts......Page 156
Chapter 8. Building a Developer Ecosystem Strategy......Page 157
  The Hobbyist......Page 158
  The Business-Focused, Tech-Savvy User......Page 159
  And Many More......Page 160
  Developer Segmentation......Page 161
  Distilling the Value Proposition......Page 165
  Defining Your Developer Funnel......Page 166
  Mapping the Current and Future State......Page 169
  Outlining Your Tactics......Page 170
 Deriving Measurements......Page 174
 Closing Thoughts......Page 175
  Getting Started......Page 177
  API Reference Documentation......Page 179
  Tutorials......Page 181
  Frequently Asked Questions......Page 182
  Landing Page......Page 183
  Changelog......Page 184
  Terms of Service......Page 185
 Samples and Snippets......Page 186
  Code Samples......Page 187
  Snippets......Page 188
 Software Development Kits and Frameworks......Page 189
  SDKs......Page 190
  Frameworks......Page 191
  Sandboxes and API Testers......Page 193
  Videos......Page 194
  Office Hours......Page 195
 Community Contribution......Page 196
 Closing Thoughts......Page 197
  Breadth and Depth Analysis......Page 199
  Top Partner Program......Page 201
  Beta Program......Page 202
  Design Sprints......Page 205
  Meetups and Community Events......Page 206
  Speaking at Events and Event Sponsorships......Page 208
  Train-the-Trainer and Ambassador Programs......Page 209
  Support, Forums, and Stack Overflow......Page 210
 Measuring Developer Programs......Page 211
 Closing Thoughts......Page 212
Chapter 11. Conclusion......Page 213
Appendix A. API Design Worksheets......Page 215
  Technology Architecture......Page 216
  Other Things We Considered......Page 217
  Errors......Page 218
  API Implementation Checklist:......Page 219
Index......Page 221
Colophon......Page 232