Principles of Web API Design: Delivering Value with APIs and Microservices, 1st edition

Nguyên tắc thiết kế API Web tập hợp các nguyên tắc và quy trình để giúp sinh viên thành công trong toàn bộ vòng đời thiết kế API. Dựa trên kinh nghiệm sâu rộng, nhà tư vấn hàng đầu James Higginbotham giúp sinh viên điều chỉnh mọi bên liên quan về kết quả cụ thể, thiết kế các API mang lại giá trị và mở rộng quy trình thiết kế từ các nhóm nhỏ đến toàn bộ tổ chức.

Higginbotham giúp sinh viên đưa góc nhìn "từ trong ra ngoài" vào thiết kế API để phản ánh tiếng nói của khách hàng và nhóm sản phẩm, ánh xạ các yêu cầu tới các API cụ thể và được tổ chức tốt, đồng thời chọn kiểu API phù hợp để viết chúng. Anh ấy xem qua một ví dụ thực tế ngay từ đầu, đưa ra hướng dẫn cho bất kỳ ai thiết kế API mới hoặc mở rộng các API hiện có.

Cung cấp các API tuyệt vời bằng cách thực hiện đúng quy trình thiết kế của sinh viên
Đạt được thỏa thuận về kết quả cụ thể từ nhóm thiết kế, khách hàng và các bên liên quan khác
Xây dựng các câu chuyện công việc, thực hiện EventStorming và mô hình hóa các khả năng
Xác định các API phù hợp và sắp xếp các hoạt động thành các cấu hình API mạch lạc
Chọn kiểu tốt nhất cho từng dự án: REST, gRPC, GraphQL hoặc API không đồng bộ dựa trên sự kiện
Tinh chỉnh thiết kế dựa trên phản hồi từ người lập tài liệu, người kiểm tra và khách hàng
Phân tách API thành microservice
Chương trình API dành cho sinh viên trưởng thành, triển khai các quy trình thiết kế và quản lý trên quy mô lớn
Hướng dẫn này rất có giá trị đối với bất kỳ ai tham gia lập kế hoạch hoặc xây dựng API—kiến trúc sư, nhà phát triển, trưởng nhóm, người quản lý trong môi trường đơn lẻ và nhiều nhóm cũng như bất kỳ chuyên gia kỹ thuật hoặc kinh doanh nào cung cấp dịch vụ "API dưới dạng sản phẩm".

Đăng ký cuốn sách này để có quyền truy cập thuận tiện vào các bản tải xuống, cập nhật và/hoặc chỉnh sửa khi chúng có sẵn. Xem sách bên trong để biết chi tiết.

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