RESTful Web API Patterns and Practices Cookbook

RESTful Web API Patterns and Practices Cookbook

by Mike Amundsen
Released October 2022
Publisher(s): O'Reilly Media, Inc.
ISBN: 9781098106744

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Buy on Amazon Buy on ebooks.com
Start your free trial

Book description

Many organizations today orchestrate and maintain apps that rely on other people's services. Software designers, developers, and architects in those companies often work to coordinate and maintain apps based on existing microservices, including third-party services that run outside their ecosystem. This cookbook provides proven recipes to help you get those many disparate parts to work together in your network.

Author Mike Amundsen provides step-by-step solutions for finding, connecting, and maintaining applications designed and built by people outside the organization. Whether you're working on human-centric mobile apps or creating high-powered machine-to-machine solutions, this guide shows you the rules, routines, commands, and protocols—the glue—that integrates individual microservices so they can function together in a safe, scalable, and reliable way.

  • Design and build individual microservices that can successfully interact on the open web
  • Increase interoperability by designing services that share a common understanding
  • Build client applications that can adapt to evolving services without breaking
  • Create resilient and reliable microservices that support peer-to-peer interactions on the web
  • Use web-based service registries to support runtime "find-and-bind" operations that manage external dependencies in real time
  • Implement stable workflows to accomplish complex, multiservice tasks consistently

Publisher resources

View/Submit Errata

Table of contents

  1. Foreword
  2. Preface
    1. About This Book
    2. Conventions Used in This Book
    3. Using Code Examples
    4. O’Reilly Online Learning
    5. How to Contact Us
    6. Acknowledgments
  3. Understanding RESTful Hypermedia
  4. 1. Introducing RESTful Web APIs
    1. What Are RESTful Web APIs?
    2. Why Hypermedia?
    3. Shared Principles for Scalable Services on the Web
  5. 2. Thinking and Designing in Hypermedia
    1. Establishing a Foundation with Hypermedia Designs
    2. Increasing Resilience with Hypermedia Clients
    3. Promoting Stability and Modifiability with Hypermedia Services
    4. Supporting Distributed Data
    5. Empowering Extensibility with Hypermedia Workflow
  6. Hypermedia Recipe Catalog
  7. 3. Hypermedia Design
    1. 3.1. Creating Interoperability with Registered Media Types
    2. 3.2. Ensuring Future Compatibility with Structured Media Types
    3. 3.3. Sharing Domain Specifics via Published Vocabularies
    4. 3.4. Describing Problem Spaces with Semantic Profiles
    5. 3.5. Expressing Actions at Runtime with Embedded Hypermedia
    6. 3.6. Designing Consistent Data Writes with Idempotent Actions
    7. 3.7. Enabling Interoperability with Inter-Service State Transfers
    8. 3.8. Designing for Repeatable Actions
    9. 3.9. Designing for Reversible Actions
    10. 3.10. Designing for Extensible Messages
    11. 3.11. Designing for Modifiable Interfaces
  8. 4. Hypermedia Clients
    1. 4.1. Limiting the Use of Hardcoded URLs
    2. 4.2. Coding Clients to Be HTTP Aware
    3. 4.3. Coding Resilient Clients with Message-Centric Implementations
    4. 4.4. Coding Effective Clients to Understand Vocabulary Profiles
    5. 4.5. Negotiating for Profile Support at Runtime
    6. 4.6. Managing Representation Formats at Runtime
    7. 4.7. Using Schema Documents as a Source of Message Metadata
    8. 4.8. Every Important Element Within a Response Needs an Identifier
    9. 4.9. Relying on Hypermedia Controls in the Response
    10. 4.10. Supporting Links and Forms for Nonhypermedia Services
    11. 4.11. Validating Data Properties at Runtime
    12. 4.12. Using Document Schemas to Validate Outgoing Messages
    13. 4.13. Using Document Queries to Validate Incoming Messages
    14. 4.14. Validating Incoming Data
    15. 4.15. Maintaining Your Own State
    16. 4.16. Having a Goal in Mind
  9. 5. Hypermedia Services
    1. 5.1. Publishing at Least One Stable URL
    2. 5.2. Preventing Internal Model Leaks
    3. 5.3. Converting Internal Models to External Messages
    4. 5.4. Expressing Internal Functions as External Actions
    5. 5.5. Advertising Support for Client Response Preferences
    6. 5.6. Supporting HTTP Content Negotiation
    7. 5.7. Publishing Complete Vocabularies for Machine Clients
    8. 5.8. Supporting Shared Vocabularies in Standard Formats
    9. 5.9. Publishing Service Definition Documents
    10. 5.10. Publishing API Metadata
    11. 5.11. Supporting Service Health Monitoring
    12. 5.12. Standardizing Error Reporting
    13. 5.13. Improving Service Discoverability with a Runtime Service Registry
    14. 5.14. Increasing Throughput with Client-Supplied Identifiers
    15. 5.15. Improving Reliability with Idempotent Create
    16. 5.16. Providing Runtime Fallbacks for Dependent Services
    17. 5.17. Using Semantic Proxies to Access Noncompliant Services
  10. 6. Distributed Data
    1. 6.1. Hiding Your Data Storage Internals
    2. 6.2. Making All Changes Idempotent
    3. 6.3. Hiding Data Relationships for External Actions
    4. 6.4. Leveraging HTTP URLs to Support “Contains” and “AND” Queries
    5. 6.5. Returning Metadata for Query Responses
    6. 6.6. Returning HTTP 200 Versus HTTP 400 for Data-Centric Queries
    7. 6.7. Using Media Types for Data Queries
    8. 6.8. Ignoring Unknown Data Fields
    9. 6.9. Improving Performance with Caching Directives
    10. 6.10. Modifying Data Models in Production
    11. 6.11. Extending Remote Data Stores
    12. 6.12. Limiting Large-Scale Responses
    13. 6.13. Using Pass-Through Proxies for Data Exchange
  11. 7. Hypermedia Workflow
    1. 7.1. Designing Workflow-Compliant Services
    2. 7.2. Supporting Shared State for Workflows
    3. 7.3. Describing Workflow as Code
    4. 7.4. Describing Workflow as DSL
    5. 7.5. Describing Workflow as Documents
    6. 7.6. Supporting RESTful Job Control Language
    7. 7.7. Exposing a Progress Resource for Your Workflows
    8. 7.8. Returning All Related Actions
    9. 7.9. Returning Most Recently Used Resources
    10. 7.10. Supporting Stateful Work in Progress
    11. 7.11. Enabling Standard List Navigation
    12. 7.12. Supporting Partial Form Submit
    13. 7.13. Using State-Watch to Enable Client-Driven Workflow
    14. 7.14. Optimizing Queries with Stored Replays
    15. 7.15. Synchronous Reply for Incomplete Work with 202 Accepted
    16. 7.16. Short-Term Fixes with Automatic Retries
    17. 7.17. Supporting Local Undo or Rollback
    18. 7.18. Calling for Help
    19. 7.19. Scaling Workflow with Queues and Clusters
    20. 7.20. Using Workflow Proxies to Enlist Noncompliant Services
  12. 8. Closing Remarks
    1. Applying These Recipes
    2. Transforming Existing Services
    3. Additional Resources
    4. Next Steps
  13. Guiding Principles of RESTful Web APIs
  14. Additional Reading
  15. Related Standards
    1. Viable Registered Media Types for RESTful Web APIs
    2. API Definition Formats
    3. Semantic Profile Document Formats
    4. Hypermedia Supporting Types
  16. Using the HyperCLI
    1. Hello, Hyper!
    2. Other Information
  17. Index
  18. About the Author

Product information

  • Title: RESTful Web API Patterns and Practices Cookbook
  • Author(s): Mike Amundsen
  • Release date: October 2022
  • Publisher(s): O'Reilly Media, Inc.
  • ISBN: 9781098106744