O'Reilly logo

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Designing Web APIs

Designing Web APIs

by Amir Shevat, Saurabh Sahni, Brenda Jin
Publisher: O'Reilly Media, Inc.
Release Date: September 2018
ISBN: 9781492026914
View table of contents
Start reading

Book Description

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

Table of Contents

  1. Preface
    1. How This Book Is Organized
    2. Conventions Used in This Book
    3. O’Reilly Safari
    4. How to Contact Us
    5. Acknowledgments
  2. 1. What’s an API?
    1. Why Do We Need APIs?
    2. Who Are Our Users?
    3. The Business Case for APIs
      1. APIs for Internal Developers First, External Developers Second
      2. APIs for External Developers First, Internal Developers Second
      3. APIs as the Product
    4. What Makes an API Great?
    5. Closing Thoughts
  3. 2. API Paradigms
    1. Request–Response APIs
      1. Representational State Transfer
      2. Remote Procedure Call
      3. GraphQL
    2. Event-Driven APIs
      1. WebHooks
      2. WebSockets
      3. HTTP Streaming
    3. Closing Thoughts
  4. 3. API Security
    1. Authentication and Authorization
    2. OAuth
      1. Token Generation
      2. Scopes
      3. Token and Scope Validation
      4. Token Expiry and Refresh Tokens
      5. Listing and Revoking Authorizations
      6. OAuth Best Practices
    3. WebHooks Security
      1. Verification Tokens
      2. Request Signing and WebHook Signatures
      3. Mutual Transport Layer Security
      4. Thin Payloads and API Retrieval
      5. WebHook Security Best Practices
    4. Closing Thoughts
  5. 4. Design Best Practices
    1. Designing for Real-Life Use Cases
    2. Designing for a Great Developer Experience
      1. Make It Fast and Easy to Get Started
      2. Work Toward Consistency
      3. Make Troubleshooting Easy
      4. Make Your API Extensible
    3. Closing Thoughts
  6. 5. Design in Practice
    1. Scenario 1
      1. Define Business Objectives
      2. Outline Key User Stories
      3. Select Technology Architecture
      4. Write an API Specification
    2. Scenario 2
      1. Define the Problem
      2. Outline Key User Stories
      3. Select Technology Architecture
      4. Write an API Specification
      5. Validate Your Decisions
    3. Closing Thoughts
  7. 6. Scaling APIs
    1. Scaling Throughput
      1. Finding the Bottlenecks
      2. Adding Computing Resources
      3. Database Indexes
      4. Caching
      5. Doing Expensive Operations Asynchronously
      6. Scaling Throughput Best Practices
    2. Evolving Your API Design
      1. Introducing New Data Access Patterns
      2. Adding New API Methods
      3. Supporting Bulk Endpoints
      4. Adding New Options to Filter Results
      5. Evolving API Design Best Practices
    3. Paginating APIs
      1. Offset-Based Pagination
      2. Cursor-Based Pagination
      3. Pagination Best Practices
    4. Rate-Limiting APIs
      1. What Is Rate-Limiting?
      2. Implementation Strategies
      3. Rate Limits and Developers
      4. Rate-Limiting Best Practices
    5. Developer SDKs
      1. Rate-Limiting Support
      2. Pagination Support
      3. Using gzip
      4. Caching Frequently Used Data
      5. Error Handling and Exponential Back-Off
      6. SDK Best Practices
    6. Closing Thoughts
  8. 7. Managing Change
    1. Toward Consistency
      1. Automated Testing
        1. API description languages
    2. Backward Compatibility
    3. Planning for and Communicating Change
      1. Communication Plan
      2. Adding
      3. Removing
      4. Versioning
    4. Closing Thoughts
  9. 8. Building a Developer Ecosystem Strategy
    1. Developers, Developers, Developers
      1. The Hobbyist
      2. The Hacker
      3. The Business-Focused, Tech-Savvy User
      4. The Professional Developer
      5. And Many More
    2. Building a Developer Strategy
    3. Developer Segmentation
    4. Distilling the Value Proposition
    5. Defining Your Developer Funnel
    6. Mapping the Current and Future State
    7. Outlining Your Tactics
    8. Deriving Measurements
    9. Closing Thoughts
  10. 9. Developer Resources
    1. API Documentation
      1. Getting Started
      2. API Reference Documentation
      3. Tutorials
      4. Frequently Asked Questions
      5. Landing Page
      6. Changelog
      7. Terms of Service
    2. Samples and Snippets
      1. Code Samples
      2. Snippets
    3. Software Development Kits and Frameworks
      1. SDKs
      2. Frameworks
    4. Development Tools
      1. Debugging and Troubleshooting
      2. Sandboxes and API Testers
    5. Rich Media
      1. Videos
      2. Office Hours
      3. Webinars and Online Training
    6. Community Contribution
    7. Closing Thoughts
  11. 10. Developer Programs
    1. Defining Your Developer Programs
      1. Breadth and Depth Analysis
    2. Deep Developer Programs
      1. Top Partner Program
      2. Beta Program
      3. Design Sprints
    3. Broad Developer Programs
      1. Meetups and Community Events
      2. Hackathons
      3. Speaking at Events and Event Sponsorships
      4. Train-the-Trainer and Ambassador Programs
      5. Online Videos and Streaming
      6. Support, Forums, and Stack Overflow
      7. Credit Program
    4. Measuring Developer Programs
    5. Closing Thoughts
  12. 11. Conclusion
  13. A. API Design Worksheets
    1. Define Business Objectives
      1. The Problem
      2. The Impact
      3. Key User Stories
      4. Technology Architecture
    2. API Specification Template
      1. Title
      2. Authors
      3. Problem
      4. Solution
      5. Implementation
      6. Authentication
      7. Other Things We Considered
      8. Inputs, Outputs (REST, RPC)
      9. Events, Payloads (Event-Driven APIs)
      10. Errors
    3. Feedback Plan
      1. API Implementation Checklist:
  14. Index