Designing Web APIs · Building APIs That Developers Love by Jin, Brenda -- Read -- Imperial Library of Trantor

Index

Preface

How This Book Is Organized Conventions Used in This Book O’Reilly Safari How to Contact Us Acknowledgments

1. What’s an API?

Why Do We Need APIs? Who Are Our Users? The Business Case for APIs

APIs for Internal Developers First, External Developers Second APIs for External Developers First, Internal Developers Second APIs as the Product

What Makes an API Great? Closing Thoughts

2. API Paradigms

Request–Response APIs

Representational State Transfer

Showing relationships Non-CRUD operations

Remote Procedure Call GraphQL

Event-Driven APIs

WebHooks WebSockets HTTP Streaming

Closing Thoughts

3. API Security

Authentication and Authorization OAuth

Token Generation Scopes Token and Scope Validation Token Expiry and Refresh Tokens Listing and Revoking Authorizations OAuth Best Practices

WebHooks Security

Verification Tokens Request Signing and WebHook Signatures

Preventing replay attacks

Mutual Transport Layer Security Thin Payloads and API Retrieval WebHook Security Best Practices

Closing Thoughts

4. Design Best Practices

Designing for Real-Life Use Cases Designing for a Great Developer Experience

Make It Fast and Easy to Get Started Work Toward Consistency Make Troubleshooting Easy

Meaningful errors Build tooling

Make Your API Extensible

Closing Thoughts

5. Design in Practice

Scenario 1

Define Business Objectives Outline Key User Stories Select Technology Architecture Write an API Specification

Scenario 2

Define the Problem Outline Key User Stories Select Technology Architecture Write an API Specification Validate Your Decisions

Reviewing the specification with stakeholders Mocking data for interactive user testing Beta testers

Closing Thoughts

6. Scaling APIs

Scaling Throughput

Finding the Bottlenecks Adding Computing Resources Database Indexes Caching Doing Expensive Operations Asynchronously Scaling Throughput Best Practices

Evolving Your API Design

Introducing New Data Access Patterns Adding New API Methods Supporting Bulk Endpoints Adding New Options to Filter Results Evolving API Design Best Practices

Paginating APIs

Offset-Based Pagination

Advantages and disadvantages

Cursor-Based Pagination

Advantages and disadvantages Choosing what goes in the cursor

Pagination Best Practices

Rate-Limiting APIs

What Is Rate-Limiting? Implementation Strategies

Token bucket Fixed-window counter Sliding-window counter

Rate Limits and Developers

Return appropriate HTTP status codes Rate-limit custom response headers Rate-limit status API Documenting rate limits

Rate-Limiting Best Practices

Developer SDKs

Rate-Limiting Support Pagination Support Using gzip Caching Frequently Used Data Error Handling and Exponential Back-Off SDK Best Practices

Closing Thoughts

7. Managing Change

Toward Consistency

Automated Testing

API description languages

Describing and validating responses Describing and validating requests

Backward Compatibility Planning for and Communicating Change

Communication Plan Adding Removing Versioning

Additive-change strategy Explicit-version strategy Versioning case study: Stripe Versioning case study: Google+ Hangouts Process management

Closing Thoughts

8. Building a Developer Ecosystem Strategy

Developers, Developers, Developers

The Hobbyist The Hacker The Business-Focused, Tech-Savvy User The Professional Developer And Many More

Building a Developer Strategy Developer Segmentation

Identity Developer proficiency Platform of choice Preferred development language, framework, and development tools Common use cases and tasks Preferred means of communication Market size and geographical distribution Real-life example

Distilling the Value Proposition Defining Your Developer Funnel

Funnel indicators

Mapping the Current and Future State Outlining Your Tactics

Awareness tactics examples Proficiency tactics examples Usage tactics examples Success tactics examples

Deriving Measurements Closing Thoughts

9. Developer Resources

API Documentation

Getting Started API Reference Documentation Tutorials Frequently Asked Questions Landing Page Changelog Terms of Service

Samples and Snippets

Code Samples Snippets

Software Development Kits and Frameworks

SDKs Frameworks

Development Tools

Debugging and Troubleshooting Sandboxes and API Testers

Rich Media

Videos Office Hours Webinars and Online Training

Community Contribution Closing Thoughts

10. Developer Programs

Defining Your Developer Programs

Breadth and Depth Analysis

Deep Developer Programs

Top Partner Program Beta Program Design Sprints

Broad Developer Programs

Meetups and Community Events Hackathons Speaking at Events and Event Sponsorships Train-the-Trainer and Ambassador Programs Online Videos and Streaming Support, Forums, and Stack Overflow Credit Program

Measuring Developer Programs Closing Thoughts

11. Conclusion A. API Design Worksheets

Define Business Objectives

The Problem The Impact Key User Stories Technology Architecture

API Specification Template

Title Authors Problem Solution Implementation Authentication Other Things We Considered Inputs, Outputs (REST, RPC) Events, Payloads (Event-Driven APIs) Errors

Feedback Plan

API Implementation Checklist:

Index

← Prev
Back
Next →

← Prev
Back
Next →