Apidays New York 2024 - RESTful API Patterns and Practices by Mike Amundsen, API Strategist

RESTful API Patterns and Practices
Mike Amundsen, Author of "Design and Build Great APIs", API Strategist & Advisor at amundsen.com, Inc.

Apidays New York 2024: The API Economy in the AI Era (April 30 & May 1, 2024)

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

Transcript

1. RESTful Web API Patterns and Practices Mike Amundsen @mamund
4. "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." -- O'Reilly Media
5. Overview • Pattern Thinking • Design • Clients • Services • Data • Workflow • Summary
6. Pattern Thinking
7. Pattern Thinking A framework for understanding, designing, and constructing systems
8. Pattern Thinking Inductive reasoning is any of various methods of reasoning in which broad generalizations or principles are derived from a body of observations.
9. Pattern Thinking "Each pattern describes a problem which occurs over and over again, and then describes the core of the solution to that problem, in such a way that you can use this solution a million times over, without ever doing it the same way twice" -- Christopher Alexander
10. Pattern Thinking Web-centric implementations rely on three key elements: messages, actions, and vocabularies.
11. Design
12. Design Patterns Design systems so that machines built by different people who have never met can successfully interact with each other.
13. Design Patterns 3.1 Creating Interoperability with Registered Media Types 3.2 Ensuring Future Compatibility with Structured Media Types 3.3 Sharing Domain Specifics Via Published Vocabularies 3.4 Describing Problem Spaces with Semantic Profiles 3.5 Expressing Domain Actions at Run-time with Embedded Hypermedia 3.6 Designing Consistent Data Writes with Idempotent Actions 3.7 Enabling Interoperability with Inter-Service State Transfers 3.8 Design for Repeatable Actions 3.9 Design for Reversible Actions 3.10 Design for Extensible Messages 3.11 Design for Modifiable Interfaces
14. Design Patterns 3.1 Creating Interoperability with Registered Media Types 3.2 Ensuring Future Compatibility with Structured Media Types 3.3 Sharing Domain Specifics Via Published Vocabularies 3.4 Describing Problem Spaces with Semantic Profiles 3.5 Expressing Domain Actions at Run-time with Embedded Hypermedia 3.6 Designing Consistent Data Writes with Idempotent Actions 3.7 Enabling Interoperability with Inter-Service State Transfers 3.8 Design for Repeatable Actions 3.9 Design for Reversible Actions 3.10 Design for Extensible Messages 3.11 Design for Modifiable Interfaces
15. Design Patterns 3.1 Creating Interoperability with Registered Media Types 3.2 Ensuring Future Compatibility with Structured Media Types 3.3 Sharing Domain Specifics Via Published Vocabularies 3.4 Describing Problem Spaces with Semantic Profiles 3.5 Expressing Domain Actions at Run-time with Embedded Hypermedia 3.6 Designing Consistent Data Writes with Idempotent Actions 3.7 Enabling Interoperability with Inter-Service State Transfers 3.8 Design for Repeatable Actions 3.9 Design for Reversible Actions 3.10 Design for Extensible Messages 3.11 Design for Modifiable Interfaces
16. Design Patterns 3.1 Creating Interoperability with Registered Media Types 3.2 Ensuring Future Compatibility with Structured Media Types 3.3 Sharing Domain Specifics Via Published Vocabularies 3.4 Describing Problem Spaces with Semantic Profiles 3.5 Expressing Domain Actions at Run-time with Embedded Hypermedia 3.6 Designing Consistent Data Writes with Idempotent Actions 3.7 Enabling Interoperability with Inter-Service State Transfers 3.8 Design for Repeatable Actions 3.9 Design for Reversible Actions 3.10 Design for Extensible Messages 3.11 Design for Modifiable Interfaces
17. Design Patterns Describing Problem Spaces with Semantic Profiles
18. Design Patterns Describing Problem Spaces with Semantic Profiles
19. Design Patterns Describing Problem Spaces with Semantic Profiles
20. Make designs composable
21. Clients
22. Client Patterns Create API consumer apps that make few assertions about how they communicate (protocol, message model, and vocabulary) with servers and let the server supply the details (the what) at runtime.
23. Client Patterns 4.1 Limiting the use of Hard-Coded URLs 4.2 Code Clients to be HTTP-Aware 4.3 Coding More Resilient Clients With Message-Centric Implementations 4.4 Coding Effective Clients to Understand Vocabulary Profiles 4.5 Negotiate for Profile Support at Runtime 4.6 Managing Representation Formats At Runtime 4.7 Using Schema Documents as a Source of Message Metadata 4.8 Every Important Element Within a Response Needs an Identifier 4.9 Relying on Hypermedia Controls In the Response 4.10 Supporting Links and Forms for Non-Hypermedia Services 4.11 Validating Data Properties At Runtime 4.12 Using Document Schemas to Validate Outgoing Messages 4.13 Using Document Queries to Validate Incoming Messages 4.14 Validating Incoming Data 4.15 Maintaining Your Own State 4.16 Having A Goal In Mind
24. Client Patterns 4.1 Limiting the use of Hard-Coded URLs 4.2 Code Clients to be HTTP-Aware 4.3 Coding More Resilient Clients With Message-Centric Implementations 4.4 Coding Effective Clients to Understand Vocabulary Profiles 4.5 Negotiate for Profile Support at Runtime 4.6 Managing Representation Formats At Runtime 4.7 Using Schema Documents as a Source of Message Metadata 4.8 Every Important Element Within a Response Needs an Identifier 4.9 Relying on Hypermedia Controls In the Response 4.10 Supporting Links and Forms for Non-Hypermedia Services 4.11 Validating Data Properties At Runtime 4.12 Using Document Schemas to Validate Outgoing Messages 4.13 Using Document Queries to Validate Incoming Messages 4.14 Validating Incoming Data 4.15 Maintaining Your Own State 4.16 Having A Goal In Mind
25. Client Patterns 4.1 Limiting the use of Hard-Coded URLs 4.2 Code Clients to be HTTP-Aware 4.3 Coding More Resilient Clients With Message-Centric Implementations 4.4 Coding Effective Clients to Understand Vocabulary Profiles 4.5 Negotiate for Profile Support at Runtime 4.6 Managing Representation Formats At Runtime 4.7 Using Schema Documents as a Source of Message Metadata 4.8 Every Important Element Within a Response Needs an Identifier 4.9 Relying on Hypermedia Controls In the Response 4.10 Supporting Links and Forms for Non-Hypermedia Services 4.11 Validating Data Properties At Runtime 4.12 Using Document Schemas to Validate Outgoing Messages 4.13 Using Document Queries to Validate Incoming Messages 4.14 Validating Incoming Data 4.15 Maintaining Your Own State 4.16 Having A Goal In Mind
26. Client Patterns 4.1 Limiting the use of Hard-Coded URLs 4.2 Code Clients to be HTTP-Aware 4.3 Coding More Resilient Clients With Message-Centric Implementations 4.4 Coding Effective Clients to Understand Vocabulary Profiles 4.5 Negotiate for Profile Support at Runtime 4.6 Managing Representation Formats At Runtime 4.7 Using Schema Documents as a Source of Message Metadata 4.8 Every Important Element Within a Response Needs an Identifier 4.9 Relying on Hypermedia Controls In the Response 4.10 Supporting Links and Forms for Non-Hypermedia Services 4.11 Validating Data Properties At Runtime 4.12 Using Document Schemas to Validate Outgoing Messages 4.13 Using Document Queries to Validate Incoming Messages 4.14 Validating Incoming Data 4.15 Maintaining Your Own State 4.16 Having A Goal In Mind
27. Client Patterns 4.1 Limiting the use of Hard-Coded URLs 4.2 Code Clients to be HTTP-Aware 4.3 Coding More Resilient Clients With Message-Centric Implementations 4.4 Coding Effective Clients to Understand Vocabulary Profiles 4.5 Negotiate for Profile Support at Runtime 4.6 Managing Representation Formats At Runtime 4.7 Using Schema Documents as a Source of Message Metadata 4.8 Every Important Element Within a Response Needs an Identifier 4.9 Relying on Hypermedia Controls In the Response 4.10 Supporting Links and Forms for Non-Hypermedia Services 4.11 Validating Data Properties At Runtime 4.12 Using Document Schemas to Validate Outgoing Messages 4.13 Using Document Queries to Validate Incoming Messages 4.14 Validating Incoming Data 4.15 Maintaining Your Own State 4.16 Having A Goal In Mind
28. Client Patterns Managing Representation Formats at Runtime
29. Client Patterns Managing Representation Formats at Runtime
30. Client Patterns Managing Representation Formats at Runtime
31. Client Patterns Managing Representation Formats at Runtime
32. Make clients adaptable
33. Services
34. Service Patterns The API is the contract — the promise that needs to be kept.
35. Service Patterns 5.1 Publishing at Least One Stable URL 5.2 Preventing Internal Model Leaks 5.3 Converting Internal Models to External Messages 5.4 Expressing Internal Functions as External Actions 5.5 Advertising Support for Client Preferences for Responses 5.6 Supporting HTTP Content Negotiation 5.7 Publishing Complete Vocabularies for Machine Clients 5.8 Supporting Shared Vocabularies in Standard Formats 5.9 Publishing Service Definition Documents 5.10 Publishing API Metadata 5.11 Supporting Service Health Monitoring 5.12 Standardizing Error Reporting 5.13 Improve Service Discoverability with a Runtime Service Registry 5.14 Increasing Throughput with Client-Supplied Identifiers 5.15 Improving Reliability with Idempotent Create 5.16 Providing Runtime Fallbacks for Dependent Services 5.17 Using Semantic Proxies to Access Non-Compliant Services
36. Service Patterns 5.1 Publishing at Least One Stable URL 5.2 Preventing Internal Model Leaks 5.3 Converting Internal Models to External Messages 5.4 Expressing Internal Functions as External Actions 5.5 Advertising Support for Client Preferences for Responses 5.6 Supporting HTTP Content Negotiation 5.7 Publishing Complete Vocabularies for Machine Clients 5.8 Supporting Shared Vocabularies in Standard Formats 5.9 Publishing Service Definition Documents 5.10 Publishing API Metadata 5.11 Supporting Service Health Monitoring 5.12 Standardizing Error Reporting 5.13 Improve Service Discoverability with a Runtime Service Registry 5.14 Increasing Throughput with Client-Supplied Identifiers 5.15 Improving Reliability with Idempotent Create 5.16 Providing Runtime Fallbacks for Dependent Services 5.17 Using Semantic Proxies to Access Non-Compliant Services
37. Service Patterns 5.1 Publishing at Least One Stable URL 5.2 Preventing Internal Model Leaks 5.3 Converting Internal Models to External Messages 5.4 Expressing Internal Functions as External Actions 5.5 Advertising Support for Client Preferences for Responses 5.6 Supporting HTTP Content Negotiation 5.7 Publishing Complete Vocabularies for Machine Clients 5.8 Supporting Shared Vocabularies in Standard Formats 5.9 Publishing Service Definition Documents 5.10 Publishing API Metadata 5.11 Supporting Service Health Monitoring 5.12 Standardizing Error Reporting 5.13 Improve Service Discoverability with a Runtime Service Registry 5.14 Increasing Throughput with Client-Supplied Identifiers 5.15 Improving Reliability with Idempotent Create 5.16 Providing Runtime Fallbacks for Dependent Services 5.17 Using Semantic Proxies to Access Non-Compliant Services
38. Service Patterns 5.1 Publishing at Least One Stable URL 5.2 Preventing Internal Model Leaks 5.3 Converting Internal Models to External Messages 5.4 Expressing Internal Functions as External Actions 5.5 Advertising Support for Client Preferences for Responses 5.6 Supporting HTTP Content Negotiation 5.7 Publishing Complete Vocabularies for Machine Clients 5.8 Supporting Shared Vocabularies in Standard Formats 5.9 Publishing Service Definition Documents 5.10 Publishing API Metadata 5.11 Supporting Service Health Monitoring 5.12 Standardizing Error Reporting 5.13 Improve Service Discoverability with a Runtime Service Registry 5.14 Increasing Throughput with Client-Supplied Identifiers 5.15 Improving Reliability with Idempotent Create 5.16 Providing Runtime Fallbacks for Dependent Services 5.17 Using Semantic Proxies to Access Non-Compliant Services
39. Improve Service Discoverability with a Runtime Service Registry Service Patterns
40. Service Patterns Improve Service Discoverability with a Runtime Service Registry
41. Make services modifiable
42. Data
43. Data Patterns "Your data model is not your object model is not your resource model is not your representation model." -- Amundsen's Maxim
44. Data Patterns 6.1 Hiding Your Data Storage Internals 6.2 Making All Changes Idempotent 6.3 Hide Data Relationships for External Actions 6.4 Leveraging HTTP URLs to Support “Contains” and “And” Queries 6.5 Returning Metadata for Query Responses 6.6 Returning HTTP 200 vs. HTTP 400 for Data-Centric Queries 6.7 Using Media Types for Data Queries 6.8 Ignore Unknown Data Fields 6.9 Improving Performance with Caching Directives 6.10 Modifying Data Models In Production 6.11 Extending Remote Data Stores 6.12 Limiting Large Scale Responses 6.13 Using Pass-Through Proxies for Data Exchange
45. Data Patterns 6.1 Hiding Your Data Storage Internals 6.2 Making All Changes Idempotent 6.3 Hide Data Relationships for External Actions 6.4 Leveraging HTTP URLs to Support “Contains” and “And” Queries 6.5 Returning Metadata for Query Responses 6.6 Returning HTTP 200 vs. HTTP 400 for Data-Centric Queries 6.7 Using Media Types for Data Queries 6.8 Ignore Unknown Data Fields 6.9 Improving Performance with Caching Directives 6.10 Modifying Data Models In Production 6.11 Extending Remote Data Stores 6.12 Limiting Large Scale Responses 6.13 Using Pass-Through Proxies for Data Exchange
46. Data Patterns 6.1 Hiding Your Data Storage Internals 6.2 Making All Changes Idempotent 6.3 Hide Data Relationships for External Actions 6.4 Leveraging HTTP URLs to Support “Contains” and “And” Queries 6.5 Returning Metadata for Query Responses 6.6 Returning HTTP 200 vs. HTTP 400 for Data-Centric Queries 6.7 Using Media Types for Data Queries 6.8 Ignore Unknown Data Fields 6.9 Improving Performance with Caching Directives 6.10 Modifying Data Models In Production 6.11 Extending Remote Data Stores 6.12 Limiting Large Scale Responses 6.13 Using Pass-Through Proxies for Data Exchange
47. Data Patterns 6.1 Hiding Your Data Storage Internals 6.2 Making All Changes Idempotent 6.3 Hide Data Relationships for External Actions 6.4 Leveraging HTTP URLs to Support “Contains” and “And” Queries 6.5 Returning Metadata for Query Responses 6.6 Returning HTTP 200 vs. HTTP 400 for Data-Centric Queries 6.7 Using Media Types for Data Queries 6.8 Ignore Unknown Data Fields 6.9 Improving Performance with Caching Directives 6.10 Modifying Data Models In Production 6.11 Extending Remote Data Stores 6.12 Limiting Large Scale Responses 6.13 Using Pass-Through Proxies for Data Exchange
48. Data Patterns Modifying Data Models in Production
49. Data Patterns Modifying Data Models in Production
50. Data Patterns Modifying Data Models in Production
51. Make data portable
52. Workflow
53. Workflow Patterns Each service that is enlisted in a workflow should be a composable service.
54. Workflow Patterns 7.1 Designing Workflow-Compliant Services 7.2 Supporting Shared State for Workflows 7.3 Describing Workflow as Code 7.4 Describing Workflow as DSL 7.5 Describing Workflow as Documents 7.6 Supporting RESTful Job Control Language 7.7 Exposing a Progress Resource for Your Workflows 7.8 Returning All Related Actions 7.9 Returning Most-Recently Used Resources (MRUs) 7.10 Supporting Stateful Work-In-Progress 7.11 Enabling Standard List Navigation 7.12 Supporting Partial Form Submit 7.13 Using State-Watch to Enable Client-Driven Workflow 7.14 Optimizing Queries With Stored Replays 7.15 Synchronous Reply for Incomplete Work with 202 Accepted 7.16 Short-Term Fixes with Automatic Retries 7.17 Supporting Local Undo/Rollback 7.18 Calling for Help 7.19 Scaling Workflow with Queues and Clusters 7.20 Using Workflow Proxies to Enlist Non-Compliant Services
55. 7.1 Designing Workflow-Compliant Services 7.2 Supporting Shared State for Workflows 7.3 Describing Workflow as Code 7.4 Describing Workflow as DSL 7.5 Describing Workflow as Documents 7.6 Supporting RESTful Job Control Language 7.7 Exposing a Progress Resource for Your Workflows 7.8 Returning All Related Actions 7.9 Returning Most-Recently Used Resources (MRUs) 7.10 Supporting Stateful Work-In-Progress 7.11 Enabling Standard List Navigation 7.12 Supporting Partial Form Submit 7.13 Using State-Watch to Enable Client-Driven Workflow 7.14 Optimizing Queries With Stored Replays 7.15 Synchronous Reply for Incomplete Work with 202 Accepted 7.16 Short-Term Fixes with Automatic Retries 7.17 Supporting Local Undo/Rollback 7.18 Calling for Help 7.19 Scaling Workflow with Queues and Clusters 7.20 Using Workflow Proxies to Enlist Non-Compliant Services Workflow Patterns
56. Workflow Patterns 7.1 Designing Workflow-Compliant Services 7.2 Supporting Shared State for Workflows 7.3 Describing Workflow as Code 7.4 Describing Workflow as DSL 7.5 Describing Workflow as Documents 7.6 Supporting RESTful Job Control Language 7.7 Exposing a Progress Resource for Your Workflows 7.8 Returning All Related Actions 7.9 Returning Most-Recently Used Resources (MRUs) 7.10 Supporting Stateful Work-In-Progress 7.11 Enabling Standard List Navigation 7.12 Supporting Partial Form Submit 7.13 Using State-Watch to Enable Client-Driven Workflow 7.14 Optimizing Queries With Stored Replays 7.15 Synchronous Reply for Incomplete Work with 202 Accepted 7.16 Short-Term Fixes with Automatic Retries 7.17 Supporting Local Undo/Rollback 7.18 Calling for Help 7.19 Scaling Workflow with Queues and Clusters 7.20 Using Workflow Proxies to Enlist Non-Compliant Services
57. Workflow Patterns 7.1 Designing Workflow-Compliant Services 7.2 Supporting Shared State for Workflows 7.3 Describing Workflow as Code 7.4 Describing Workflow as DSL 7.5 Describing Workflow as Documents 7.6 Supporting RESTful Job Control Language 7.7 Exposing a Progress Resource for Your Workflows 7.8 Returning All Related Actions 7.9 Returning Most-Recently Used Resources (MRUs) 7.10 Supporting Stateful Work-In-Progress 7.11 Enabling Standard List Navigation 7.12 Supporting Partial Form Submit 7.13 Using State-Watch to Enable Client-Driven Workflow 7.14 Optimizing Queries With Stored Replays 7.15 Synchronous Reply for Incomplete Work with 202 Accepted 7.16 Short-Term Fixes with Automatic Retries 7.17 Supporting Local Undo/Rollback 7.18 Calling for Help 7.19 Scaling Workflow with Queues and Clusters 7.20 Using Workflow Proxies to Enlist Non-Compliant Services
58. Workflow Patterns RESTful Job Control Language
59. Workflow Patterns RESTful Job Control Language
60. Workflow Patterns RESTful Job Control Language
61. Workflow Patterns RESTful Job Control Language
62. Workflow Patterns RESTful Job Control Language
63. Workflow Patterns RESTful Job Control Language
64. Make workflow flexible
65. And so …
66. Goals • Make designs composable • Make clients adaptable • Make services modifiable • Make data portable • Make workflow flexible
67. Goals • Make designs composable • Make clients adaptable • Make services modifiable • Make data portable • Make workflow flexible
68. Goals • Make designs composable • Make clients adaptable • Make services modifiable • Make data portable • Make workflow flexible
69. Goals • Make designs composable • Make clients adaptable • Make services modifiable • Make data portable • Make workflow flexible
70. Goals • Make designs composable • Make clients adaptable • Make services modifiable • Make data portable • Make workflow flexible
71. Goals • Make designs composable • Make clients adaptable • Make services modifiable • Make data portable • Make workflow flexible
72. The RESTful Web API Principle "Leverage global reach to solve problems you haven’t thought of for people you have never met."
73. The RESTful Web API Principle "Leverage global reach to solve problems you haven’t thought of for people you have never met."
74. The RESTful Web API Principle "Leverage global reach to solve problems you haven’t thought of for people you have never met."
75. The RESTful Web API Principle "Leverage global reach to solve problems you haven’t thought of for people you have never met."
76. The RESTful Web API Principle "Leverage global reach to solve problems you haven’t thought of for people you have never met."
77. The RESTful Web API Principle "Leverage global reach to solve problems you haven’t thought of for people you have never met."
78. Pattern Thinking -- and Models "Everything we think we know about the world is a model." -- Donella Meadows, 2008
79. Pattern Thinking "The difference between the novice and the teacher is simply that the novice has not learnt, yet, how to do things in such a way that they can afford to make small mistakes." -- Christopher Alexander
80. Pattern Thinking "The difference between the novice and the teacher is simply that the novice has not learnt, yet, how to do things in such a way that they can afford to make small mistakes." -- Christopher Alexander
81. RESTful Web API Patterns and Practices Mike Amundsen @mamund
82. RESTful Web API Patterns and Practices Mike Amundsen @mamund