Principles of Web API Design
Delivering Value with APIs and Microservices
Published on 5. March 2022
Book
Paperback/Softback
368 pages
978-0-13-735563-1 (ISBN)
Description
The Full-Lifecycle Guide to API Design
Principles of Web API Design brings together principles and processes to help you succeed across the entire API design lifecycle. Drawing on extensive in-the-trenches experience, leading consultant James Higginbotham helps you align every stakeholder on specific outcomes, design APIs that deliver value, and scale the design process from small teams to the entire organization.
Higginbotham helps you bring an "outside-in" perspective to API design to reflect the voices of customers and product teams, map requirements to specific and well-organized APIs, and choose the right API style for writing them. He walks through a real-world example from the ground up, offering guidance for anyone designing new APIs or extending existing APIs.
Deliver great APIs by getting your design processes right
Gain agreement on specific outcomes from design teams, customers, and other stakeholders
Craft job stories, conduct EventStorming, and model capabilities
Identify the right APIs, and organize operations into coherent API profiles
Choose the best styles for each project: REST, gRPC, GraphQL, or event-based async APIs
Refine designs based on feedback from documenters, testers, and customers
Decompose APIs into microservices
Mature your API program, implementing design and management processes that scale
This guide is invaluable for anyone involved in planning or building APIs--architects, developers, team leaders, managers in single and multi-team environments, and any technical or business professional delivering "API-as-a-product" offerings.
Register your book for convenient access to downloads, updates, and/or corrections as they become available. See inside book for details.
Principles of Web API Design brings together principles and processes to help you succeed across the entire API design lifecycle. Drawing on extensive in-the-trenches experience, leading consultant James Higginbotham helps you align every stakeholder on specific outcomes, design APIs that deliver value, and scale the design process from small teams to the entire organization.
Higginbotham helps you bring an "outside-in" perspective to API design to reflect the voices of customers and product teams, map requirements to specific and well-organized APIs, and choose the right API style for writing them. He walks through a real-world example from the ground up, offering guidance for anyone designing new APIs or extending existing APIs.
Deliver great APIs by getting your design processes right
Gain agreement on specific outcomes from design teams, customers, and other stakeholders
Craft job stories, conduct EventStorming, and model capabilities
Identify the right APIs, and organize operations into coherent API profiles
Choose the best styles for each project: REST, gRPC, GraphQL, or event-based async APIs
Refine designs based on feedback from documenters, testers, and customers
Decompose APIs into microservices
Mature your API program, implementing design and management processes that scale
This guide is invaluable for anyone involved in planning or building APIs--architects, developers, team leaders, managers in single and multi-team environments, and any technical or business professional delivering "API-as-a-product" offerings.
Register your book for convenient access to downloads, updates, and/or corrections as they become available. See inside book for details.
Reviews / Votes
"I've had the good fortune to work alongside and learn from James over the past several years. His varied institutional knowledge, along with his depth of experience and eye for practical application, makes him unique among his peers. I am ecstatic that others now have the opportunity, in this book, to benefit from James's compelling, pragmatic vision for how to make better APIs. Principles of Web API Design surveys the gamut of available techniques and sets forth a prescriptive, easy-to-follow approach. Teams that apply the guidance in this book will create APIs that better resonate with customers, deliver more business value in less time, and require fewer breaking changes. I cannot recommend Principles of Web API Design enough."--Matthew Reinbold, Director of API Ecosystems, Postman
"In modern software development, APIs end up being both the cause of and solution to many of the problems we face. James's process for dissecting, analyzing, and designing APIs from concepts to caching creates a repeatable approach for teams to solve more problems than they create."
--D. Keith Casey, Jr., API Problem Solver, CaseySoftware, LLC
"Following James's clear and easy-to-follow guide, in one afternoon I was able to apply his process to current real-world use cases. I now have the practical guidance, techniques, and clear examples to help me take those next vital steps. Recommended reading for anyone connected to and working with APIs."
--Joyce Stack, Architect, Elsevier
" Principles of Web API Design uncovers more than principles. In it, you'll learn a process--a method to design APIs."
--Arnaud Lauret, API Handyman
"This insightful playbook guides API teams through a structured process that fosters productive collaboration, valuable capability identification, and best-practice contract crafting. James distills years of experience into a pragmatic roadmap for defining and refining API products, and also provides a primer for API security, eventing, resiliency, and microservices alignment. A must-read for architects either new to the API discipline or responsible for onboarding new teams and instituting a structured API definition process."
--Chris Haddad, Chief Architect, Karux LLC
More details
Series
Language
English
Place of publication
Boston
United States
Publishing group
Pearson Education (US)
Target group
Professional and scholarly
Product notice
Paperback (trade)
Unsewn / adhesive bound
Dimensions
Height: 226 mm
Width: 182 mm
Thickness: 22 mm
Weight
697 gr
ISBN-13
978-0-13-735563-1 (9780137355631)
Copyright in bibliographic data and cover images is held by Nielsen Book Services Limited or by the publishers or by their respective licensors: all rights reserved.
Schweitzer Classification
Other editions
Additional editions
E-Book
01/2022
1st Edition
Addison Wesley
€41.99
Available for download
E-Book
01/2022
1st Edition
Addison Wesley
€41.99
Available for download
Person
James Higginbotham is a software developer and architect with over 25 years of experience in developing and deploying apps and APIs. He guides enterprises through their digital transformation journey, ensuring alignment between business and technology through product-based thinking to deliver a great customer experience. James engages with teams and organizations to help them align their business, product, and technology strategies into a more composable and modular enterprise platform. James also delivers workshops that help cross-functional teams to apply an API design-first approach using his ADDR process. His industry experience includes banking, commercial insurance, hospitality, travel, and the airline industry where he helped to get an airline off the ground--literally. You can learn more about his latest efforts at https://launchany.com and on Twitter @launchany.
Content
Series Editor Foreword xxi
Foreword xxv
Preface xxvii
Acknowledgments xxxi
About the Author xxxiii
Part I: Introduction to Web API Design 1
Chapter 1: The Principles of API Design 3
The Elements of Web API Design 4
API Design Is Communication 6
Reviewing the Principles of Software Design 7
Resource-Based API Design 10
Resources Are Not Object or Domain Models 11
Resource-Based APIs Exchange Messages 12
The Principles of Web API Design 13
Summary 14
Chapter 2: Collaborative API Design 15
Why an API Design Process? 15
API Design Process Antipatterns 16
The API Design-First Approach 20
Remaining Agile with API Design-First 22
The Align-Define-Design-Refine Process 23
The Role of DDD in API Design 26
API Design Involves Everyone 26
Applying the Process Effectively 28
Summary 28
Part II: Aligning on API Outcomes 29
Chapter 3: Identify Digital Capabilities 31
Ensuring Stakeholder Alignment 32
What Are Digital Capabilities? 33
Focusing on the Jobs to Be Done 34
What Are Job Stories? 35
The Components of a Job Story 36
Writing Job Stories for APIs 37
Overcoming Job Story Challenges 38
Techniques for Capturing Job Stories 40
A Real-World API Design Project 41
Job Story Examples 42
Summary 42
Chapter 4: Capture Activities and Steps 45
Extending Job Stories into Activities and Steps 46
Using EventStorming for Collaborative Understanding 49
How EventStorming Works 50
The Benefits of EventStorming 58
Facilitating an EventStorming Session 60
Customizing the Process 64
Summary 65
Part III: Defining Candidate APIs 67
Chapter 5: Identifying API Boundaries 69
Avoiding API Boundary Antipatterns 70
Bounded Contexts, Subdomains, and APIs 72
Finding API Boundaries Using EventStorming 73
Finding API Boundaries through Activities 73
Naming and Scoping APIs 75
Summary 78
Chapter 6: API Modeling 79
What Is API Modeling? 80
The API Modeling Process 81
Validating the API Model with Sequence Diagrams 93
Evaluating API Priority and Reuse 95
Summary 96
Part IV: Designing APIs 99
Chapter 7: REST-Based API Design 101
What Is a REST-Based API? 102
REST API Design Process 112
Selecting a Representation Format 125
Common REST Design Patterns 132
Summary 136
Chapter 8: RPC and Query-Based API Design 137
What Is an RPC-Based API? 138
RPC API Design Process 142
What Is a Query-Based API? 146
Query-Based API Design Process 150
Summary 157
Chapter 9: Async APIs for Eventing and Streaming 159
The Problem with API Polling 160
Async APIs Create New Possibilities 161
A Review of Messaging Fundamentals 162
Async API Styles 171
Designing Async APIs 178
Documenting Async APIs 184
Summary 186
Part V: Refining the API Design 187
Chapter 10: From APIs to Microservices 189
What Are Microservices? 190
Microservices Reduce Coordination Costs 192
The Difference between APIs and Microservices 193
Weighing the Complexity of Microservices 193
Synchronous and Asynchronous Microservices 198
Microservice Architecture Styles 201
Right-Sizing Microservices 204
Decomposing APIs into Microservices 204
Considerations When Transitioning to Microservices 210
Summary 211
Chapter 11: Improving the Developer Experience 213
Creating a Mock API Implementation 214
Providing Helper Libraries and SDKs 219
Offering CLIs for APIs 221
Summary 224
Chapter 12: API Testing Strategies 225
Acceptance Testing 226
Automated Security Testing 226
Operational Monitoring 227
API Contract Testing 227
Selecting Tools to Accelerate Testing 229
The Challenges of API Testing 230
Make API Testing Essential 231
Summary 231
Chapter 13: Document the API Design 233
The Importance of API Documentation 234
API Description Formats 234
Extending Docs with Code Examples 248
From Reference Docs to a Developer Portal 251
Effective API Documentation 253
The Minimum Viable Portal 256
Tools and Frameworks for Developer Portals 259
Summary 260
Chapter 14: Designing for Change 261
The Impact of Change on Existing APIs 261
API Versioning Strategies 264
Deprecating APIs 268
Establishing an API Stability Contract 270
Summary 271
Chapter 15: Protecting APIs 273
The Potential for API Mischief 273
Essential API Protection Practices 274
Components of API Protection 276
API Gateway Topologies 279
Identity and Access Management 284
Considerations before Building an In-House API Gateway 289
Summary 291
Chapter 16: Continuing the API Design Journey 293
Establishing an API Style Guide 293
Conducting API Design Reviews 297
Developing a Culture of Reuse 300
The Journey Has Only Begun 301
Appendix: HTTP Primer 303
Index 319
Foreword xxv
Preface xxvii
Acknowledgments xxxi
About the Author xxxiii
Part I: Introduction to Web API Design 1
Chapter 1: The Principles of API Design 3
The Elements of Web API Design 4
API Design Is Communication 6
Reviewing the Principles of Software Design 7
Resource-Based API Design 10
Resources Are Not Object or Domain Models 11
Resource-Based APIs Exchange Messages 12
The Principles of Web API Design 13
Summary 14
Chapter 2: Collaborative API Design 15
Why an API Design Process? 15
API Design Process Antipatterns 16
The API Design-First Approach 20
Remaining Agile with API Design-First 22
The Align-Define-Design-Refine Process 23
The Role of DDD in API Design 26
API Design Involves Everyone 26
Applying the Process Effectively 28
Summary 28
Part II: Aligning on API Outcomes 29
Chapter 3: Identify Digital Capabilities 31
Ensuring Stakeholder Alignment 32
What Are Digital Capabilities? 33
Focusing on the Jobs to Be Done 34
What Are Job Stories? 35
The Components of a Job Story 36
Writing Job Stories for APIs 37
Overcoming Job Story Challenges 38
Techniques for Capturing Job Stories 40
A Real-World API Design Project 41
Job Story Examples 42
Summary 42
Chapter 4: Capture Activities and Steps 45
Extending Job Stories into Activities and Steps 46
Using EventStorming for Collaborative Understanding 49
How EventStorming Works 50
The Benefits of EventStorming 58
Facilitating an EventStorming Session 60
Customizing the Process 64
Summary 65
Part III: Defining Candidate APIs 67
Chapter 5: Identifying API Boundaries 69
Avoiding API Boundary Antipatterns 70
Bounded Contexts, Subdomains, and APIs 72
Finding API Boundaries Using EventStorming 73
Finding API Boundaries through Activities 73
Naming and Scoping APIs 75
Summary 78
Chapter 6: API Modeling 79
What Is API Modeling? 80
The API Modeling Process 81
Validating the API Model with Sequence Diagrams 93
Evaluating API Priority and Reuse 95
Summary 96
Part IV: Designing APIs 99
Chapter 7: REST-Based API Design 101
What Is a REST-Based API? 102
REST API Design Process 112
Selecting a Representation Format 125
Common REST Design Patterns 132
Summary 136
Chapter 8: RPC and Query-Based API Design 137
What Is an RPC-Based API? 138
RPC API Design Process 142
What Is a Query-Based API? 146
Query-Based API Design Process 150
Summary 157
Chapter 9: Async APIs for Eventing and Streaming 159
The Problem with API Polling 160
Async APIs Create New Possibilities 161
A Review of Messaging Fundamentals 162
Async API Styles 171
Designing Async APIs 178
Documenting Async APIs 184
Summary 186
Part V: Refining the API Design 187
Chapter 10: From APIs to Microservices 189
What Are Microservices? 190
Microservices Reduce Coordination Costs 192
The Difference between APIs and Microservices 193
Weighing the Complexity of Microservices 193
Synchronous and Asynchronous Microservices 198
Microservice Architecture Styles 201
Right-Sizing Microservices 204
Decomposing APIs into Microservices 204
Considerations When Transitioning to Microservices 210
Summary 211
Chapter 11: Improving the Developer Experience 213
Creating a Mock API Implementation 214
Providing Helper Libraries and SDKs 219
Offering CLIs for APIs 221
Summary 224
Chapter 12: API Testing Strategies 225
Acceptance Testing 226
Automated Security Testing 226
Operational Monitoring 227
API Contract Testing 227
Selecting Tools to Accelerate Testing 229
The Challenges of API Testing 230
Make API Testing Essential 231
Summary 231
Chapter 13: Document the API Design 233
The Importance of API Documentation 234
API Description Formats 234
Extending Docs with Code Examples 248
From Reference Docs to a Developer Portal 251
Effective API Documentation 253
The Minimum Viable Portal 256
Tools and Frameworks for Developer Portals 259
Summary 260
Chapter 14: Designing for Change 261
The Impact of Change on Existing APIs 261
API Versioning Strategies 264
Deprecating APIs 268
Establishing an API Stability Contract 270
Summary 271
Chapter 15: Protecting APIs 273
The Potential for API Mischief 273
Essential API Protection Practices 274
Components of API Protection 276
API Gateway Topologies 279
Identity and Access Management 284
Considerations before Building an In-House API Gateway 289
Summary 291
Chapter 16: Continuing the API Design Journey 293
Establishing an API Style Guide 293
Conducting API Design Reviews 297
Developing a Culture of Reuse 300
The Journey Has Only Begun 301
Appendix: HTTP Primer 303
Index 319