RESTful Web API Patterns and Practices Cookbook: Connecting and Orchestrating Microservices and Distributed Data [1 ed.] 1098106741, 9781098106744

Table of contents :
Cover
Copyright
Table of Contents
Foreword
Preface
About This Book
Who Should Read This Book
What’s Covered
What’s Not Covered
About These Recipes
How to Use This Book
Conventions Used in This Book
Using Code Examples
O’Reilly Online Learning
How to Contact Us
Acknowledgments
Part I. Understanding RESTful Hypermedia
Chapter 1. Introducing RESTful Web APIs
What Are RESTful Web APIs?
Fielding’s REST
The Web of Tim Berners-Lee
Alan Kay’s Extreme Late Binding
Why Hypermedia?
Hypermedia: A Definition
A Century of Hypermedia
The Value of Messages
The Power of Vocabularies
Richardson’s Magic Strings
Shared Principles for Scalable Services on the Web
Leverage Global Reach…
…to Solve Problems You Haven’t Thought of…
…for People You Have Never Met
Dealing with Timescales
This Will All Change
Chapter 2. Thinking and Designing in Hypermedia
Establishing a Foundation with Hypermedia Designs
Licklider’s Aliens
Morville’s Information Architecture
Hypermedia and “A Priori Design”
Increasing Resilience with Hypermedia Clients
Binding to Protocols and Formats
Runtime Resolution with Metadata
Machine-to-Machine Challenges
Relying on Semantic Vocabularies
Supporting Client-Centric Workflows
Promoting Stability and Modifiability with Hypermedia Services
The Modifiability Problem
How Hypermedia Can Help
From Self-Servicing to Find and Bind
Supporting Distributed Data
Data Is Evidence of Action
Outside Versus Inside
Read Versus Write
Robust Data Languages
Empowering Extensibility with Hypermedia Workflow
Choreography, Orchestration, and Hypermedia Workflow
Workflow Challenges
Quick Summary
Part II. Hypermedia Recipe Catalog
Chapter 3. Hypermedia Design
3.1 Creating Interoperability with Registered Media Types
Problem
Solution
Discussion
See Also
3.2 Ensuring Future Compatibility with Structured Media Types
Problem
Solution
Example
Discussion
See Also
3.3 Sharing Domain Specifics via Published Vocabularies
Problem
Solution
Example
Discussion
See Also
3.4 Describing Problem Spaces with Semantic Profiles
The Problem
The Solution
Example
Discussion
See Also
3.5 Expressing Actions at Runtime with Embedded Hypermedia
Problem
Solution
Example
Discussion
See Also
3.6 Designing Consistent Data Writes with Idempotent Actions
Problem
Solution
Example
Discussion
See Also
3.7 Enabling Interoperability with Inter-Service State Transfers
Problem
Solution
Example
Discussion
See Also
3.8 Designing for Repeatable Actions
Problem
Solution
Example
Discussion
See Also
3.9 Designing for Reversible Actions
Problem
Solution
Example
Discussion
See Also
3.10 Designing for Extensible Messages
Problem
Solution
Example
Discussion
See Also
3.11 Designing for Modifiable Interfaces
Problem
Solution
Example
Discussion
See Also
Chapter 4. Hypermedia Clients
4.1 Limiting the Use of Hardcoded URLs
Problem
Solution
Example
Discussion
See Also
4.2 Coding Clients to Be HTTP Aware
Problem
Solution
Example
Discussion
See Also
4.3 Coding Resilient Clients with Message-Centric Implementations
Problem
Solution
Example
Discussion
See Also
4.4 Coding Effective Clients to Understand Vocabulary Profiles
Problem
Solution
Example
Discussion
See Also
4.5 Negotiating for Profile Support at Runtime
Problem
Solution
Example
Discussion
See Also
4.6 Managing Representation Formats at Runtime
Problem
Solution
Example
Discussion
See Also
4.7 Using Schema Documents as a Source of Message Metadata
Problem
Solution
Example
Discussion
See Also
4.8 Every Important Element Within a Response Needs an Identifier
Problem
Solution
Example
Discussion
See Also
4.9 Relying on Hypermedia Controls in the Response
Problem
Solution
Example
Discussion
See Also
4.10 Supporting Links and Forms for Nonhypermedia Services
Problem
Solution
Example
Discussion
See Also
4.11 Validating Data Properties at Runtime
Problem
Solution
Example
Discussion
See Also
4.12 Using Document Schemas to Validate Outgoing Messages
Problem
Solution
Example
Discussion
See Also
4.13 Using Document Queries to Validate Incoming Messages
Problem
Solution
Example
Discussion
See Also
4.14 Validating Incoming Data
Problem
Solution
Example
Discussion
See Also
4.15 Maintaining Your Own State
Problem
Solution
Example
Discussion
See Also
4.16 Having a Goal in Mind
Problem
Solution
Example
Discussion
See Also
Chapter 5. Hypermedia Services
5.1 Publishing at Least One Stable URL
Problem
Solution
Example
Discussion
See Also
5.2 Preventing Internal Model Leaks
Problem
Solution
Example
Discussion
See Also
5.3 Converting Internal Models to External Messages
Problem
Solution
Example
Discussion
See Also
5.4 Expressing Internal Functions as External Actions
Problem
Solution
Example
Discussion
See Also
5.5 Advertising Support for Client Response Preferences
Problem
Solution
Example
Discussion
See Also
5.6 Supporting HTTP Content Negotiation
Problem
Solution
Example
Discussion
See Also
5.7 Publishing Complete Vocabularies for Machine Clients
Problem
Solution
Example
Discussion
See Also
5.8 Supporting Shared Vocabularies in Standard Formats
Problem
Solution
Example
Discussion
See Also
5.9 Publishing Service Definition Documents
Problem
Solution
Example
Discussion
See Also
5.10 Publishing API Metadata
Problem
Solution
Example
Discussion
See Also
5.11 Supporting Service Health Monitoring
Problem
Solution
Example
Discussion
See Also
5.12 Standardizing Error Reporting
Problem
Solution
Example
Discussion
See Also
5.13 Improving Service Discoverability with a Runtime Service Registry
Problem
Solution
Example
Discussion
See Also
5.14 Increasing Throughput with Client-Supplied Identifiers
Problem
Solution
Example
Discussion
See Also
5.15 Improving Reliability with Idempotent Create
Problem
Solution
Example
Discussion
See Also
5.16 Providing Runtime Fallbacks for Dependent Services
Problem
Solution
Example
Discussion
See Also
5.17 Using Semantic Proxies to Access Noncompliant Services
Problem
Solution
Example
Discussion
See Also
Chapter 6. Distributed Data
6.1 Hiding Your Data Storage Internals
Problem
Solution
Example
Discussion
See Also
6.2 Making All Changes Idempotent
Problem
Solution
Example
Discussion
See Also
6.3 Hiding Data Relationships for External Actions
Problem
Solution
Example
Discussion
See Also
6.4 Leveraging HTTP URLs to Support “Contains” and “AND” Queries
Problem
Solution
Example
Discussion
See Also
6.5 Returning Metadata for Query Responses
Problem
Solution
Example
Discussion
See Also
6.6 Returning HTTP 200 Versus HTTP 400 for Data-Centric Queries
Problem
Solution
Example
Discussion
See Also
6.7 Using Media Types for Data Queries
Problem
Solution
Example
Discussion
See Also
6.8 Ignoring Unknown Data Fields
Problem
Solution
Example
Discussion
See Also
6.9 Improving Performance with Caching Directives
Problem
Solution
Example
Discussion
See Also
6.10 Modifying Data Models in Production
Problem
Solution
Example
Discussion
See Also
6.11 Extending Remote Data Stores
Problem
Solution
Example
Discussion
See Also
6.12 Limiting Large-Scale Responses
Problem
Solution
Example
Discussion
See Also
6.13 Using Pass-Through Proxies for Data Exchange
Problem
Solution
Example
Discussion
See Also
Chapter 7. Hypermedia Workflow
7.1 Designing Workflow-Compliant Services
Problem
Solution
Example
Discussion
See Also
7.2 Supporting Shared State for Workflows
Problem
Solution
Example
Discussion
See Also
7.3 Describing Workflow as Code
Problem
Solution
Example
Discussion
See Also
7.4 Describing Workflow as DSL
Problem
Solution
Example
Discussion
See Also
7.5 Describing Workflow as Documents
Problem
Solution
Example
Discussion
See Also
7.6 Supporting RESTful Job Control Language
Problem
Solution
Discussion
See Also
7.7 Exposing a Progress Resource for Your Workflows
Problem
Solution
Example
Discussion
See Also
7.8 Returning All Related Actions
Problem
Solution
Example
Discussion
See Also
7.9 Returning Most Recently Used Resources
Problem
Solution
Example
Discussion
See Also
7.10 Supporting Stateful Work in Progress
Problem
Solution
Example
Discussion
See Also
7.11 Enabling Standard List Navigation
Problem
Solution
Example
Discussion
See Also
7.12 Supporting Partial Form Submit
Problem
Solution
Example
Discussion
See Also
7.13 Using State-Watch to Enable Client-Driven Workflow
Problem
Solution
Typical State-Watch Interaction
Example
Discussion
See Also
7.14 Optimizing Queries with Stored Replays
Problem
Solution
Example
Discussion
See Also
7.15 Synchronous Reply for Incomplete Work with 202 Accepted
Problem
Solution
Example
Discussion
See Also
7.16 Short-Term Fixes with Automatic Retries
Problem
Solution
Example
Discussion
See Also
7.17 Supporting Local Undo or Rollback
Problem
Solution
Example
Discussion
See Also
7.18 Calling for Help
Problem
Solution
Example
Discussion
See Also
7.19 Scaling Workflow with Queues and Clusters
Problem
Solution
Discussion
See Also
7.20 Using Workflow Proxies to Enlist Noncompliant Services
Problem
Solution
Example
Discussion
See Also
Chapter 8. Closing Remarks
Applying These Recipes
Design First
Clients and Servers Unite!
Starting with Data Is Challenging
Going with the Flow
Transforming Existing Services
Additional Resources
Next Steps
Appendix A. Guiding Principles of RESTful Web APIs
Appendix B. Additional Reading
Appendix C. Related Standards
Viable Registered Media Types for RESTful Web APIs
Structured Media Types
Unstructured Media Types
Unregistered Media Types
API Definition Formats
Semantic Profile Document Formats
Hypermedia Supporting Types
Appendix D. Using the HyperCLI
Hello, Hyper!
Other Information
HyperCLI Commands
Index
About the Author