Mastering API Architecture Design, Operate, and Evolve API-Based Systems (James Gough, Daniel Bryant, Matthew Auburn) (Z-Library)

📄 File Format: PDF

💾 File Size: 9.3 MB

📖 Read Online ⬇️ Download

Registered users can read the full content for free

Register as a Gaohf Library member to read the complete e-book online for free and enjoy a better reading experience.

📄 Page 1

James Gough, Daniel Bryant & Matthew Auburn Foreword by Sarah Wells Mastering API Architecture Design, Operate, and Evolve API-Based Systems G oug h, B rya nt & A ub urn M a stering A PI A rchitecture M a stering A PI A rchitecture

📄 Page 2

SOF T WARE ARCHITEC TURE “With so much attention on containers and microser- vices, people often ignore the fundamentals around how their services commu- nicate. This book sets this right, with an in-depth look at how to structure and evolve your APIs.” —Sam Newman author of Building Microservices “Excellently written with lots of tips, examples, and practical advice.” —Stefania Chaplin GitLab & DevStefOps Mastering API Architecture US $59.99 CAN $74.99 ISBN: 978-1-492-09063-2 Twitter: @oreillymedia linkedin.com/company/oreilly-media youtube.com/oreillymedia Most organizations with a web presence build and operate APIs—the doorway for customers to begin their interaction with the company’s services. Designing, building, and managing these critical programs affects everyone in the organization, from engineers and product owners to C-suite executives. But the real challenge for developers and solution architects is creating an API platform from the ground up. With this practical book, you’ll learn strategies for building and testing REST APIs that use API gateways to combine offerings at the microservice level. Authors James Gough, Daniel Bryant, and Matthew Auburn explain how simple additions to this infrastructure can help engineers and organizations migrate toward the cloud —and open the opportunity to connect internal services using technologies like a service mesh. • Learn API fundamentals and architectural patterns for building an API platform • Use practical examples to understand how to design, build, and test API-based systems • Deploy, operate, and configure key components of an API platform • Use API gateways and service meshes appropriately, based on case studies • Understand core security and common vulnerabilities in API architecture • Secure data and APIs using threat modeling and technologies like OAuth2 and TLS • Learn how to evolve existing systems toward API- and cloud- based architectures James Gough is a Distinguished Engineer at Morgan Stanley, a Java Champion, and coauthor of Optimizing Java. Daniel Bryant is head of developer relations at Ambassador Labs and a Java Champion. His expertise is in DevOps tooling, cloud/container platforms, and microservices. Matthew Auburn is a VP at Morgan Stanley. He has worked on financial systems, on mobile and web applications, and in API security. G oug h, B rya nt & A ub urn

📄 Page 3

James Gough, Daniel Bryant, and Matthew Auburn Mastering API Architecture Design, Operate, and Evolve API-Based Systems Boston Farnham Sebastopol TokyoBeijing

📄 Page 4

978-1-492-09063-2 [LSI] Mastering API Architecture by James Gough, Daniel Bryant, and Matthew Auburn Copyright © 2023 James Gough Ltd, Big Picture Tech Ltd, and Matthew Auburn Ltd. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://oreilly.com). For more information, contact our corporate/institutional sales department: 800-998-9938 or corporate@oreilly.com. Acquisitions Editor: Melissa Duffield Development Editor: Virginia Wilson Production Editor: Clare Laylock Copyeditor: Kim Cofer Proofreader: Amnet Systems LLC Indexer: nSight, Inc. Interior Designer: David Futato Cover Designer: Karen Montgomery Illustrator: Kate Dullea October 2022: First Edition Revision History for the First Edition 2022-10-17: First Release See http://oreilly.com/catalog/errata.csp?isbn=9781492090632 for release details. The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Mastering API Architecture, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. While the publisher and the authors have used good faith efforts to ensure that the information and instructions contained in this work are accurate, the publisher and the authors disclaim all responsibility for errors or omissions, including without limitation responsibility for damages resulting from the use of or reliance on this work. Use of the information and instructions contained in this work is at your own risk. If any code samples or other technology this work contains or describes is subject to open source licenses or the intellectual property rights of others, it is your responsibility to ensure that your use thereof complies with such licenses and/or rights.

📄 Page 5

This book is dedicated to Alex Blewitt, who unfortunately passed away before publication. We would like to thank Alex for his candid feedback, constant support, and warm friendship over the years. —The Authors

📄 Page 6

(This page has no text content)

📄 Page 7

Table of Contents Foreword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii Part I. Designing, Building, and Testing APIs 1. Design, Build, and Specify APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Case Study: Designing the Attendee API 3 Introduction to REST 4 Introduction to REST and HTTP by Example 4 The Richardson Maturity Model 5 Introduction to Remote Procedure Call (RPC) APIs 6 A Brief Mention of GraphQL 7 REST API Standards and Structure 8 Collections and Pagination 10 Filtering Collections 10 Error Handling 11 ADR Guideline: Choosing an API Standard 12 Specifying REST APIs Using OpenAPI 12 Practical Application of OpenAPI Specifications 13 Code Generation 13 OpenAPI Validation 13 Examples and Mocking 14 Detecting Changes 15 API Versioning 15 Semantic Versioning 16 v

📄 Page 8

OpenAPI Specification and Versioning 16 Implementing RPC with gRPC 18 Modeling Exchanges and Choosing an API Format 20 High-Traffic Services 20 Large Exchange Payloads 20 HTTP/2 Performance Benefits 21 Vintage Formats 21 Guideline: Modeling Exchanges 22 Multiple Specifications 22 Does the Golden Specification Exist? 22 Challenges of Combined Specifications 23 Summary 24 2. Testing APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Conference System Scenario for This Chapter 28 Testing Strategies 29 Test Quadrant 29 Test Pyramid 31 ADR Guideline for Testing Strategies 34 Contract Testing 34 Why Contract Testing Is Often Preferable 34 How a Contract Is Implemented 35 ADR Guideline: Contract Testing 40 API Component Testing 41 Contract Testing Versus Component Testing 42 Case Study: Component Test to Verify Behavior 42 API Integration Testing 44 Using Stub Servers: Why and How 44 ADR Guideline: Integration Testing 46 Containerizing Test Components: Testcontainers 47 Case Study: Applying Testcontainers to Verify Integrations 47 End-to-End Testing 49 Automating End-to-End Validation 49 Types of End-to-End Tests 50 ADR Guideline: End-to-End Testing 51 Summary 52 Part II. API Traffic Management 3. API Gateways: Ingress Traffic Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Is an API Gateway the Only Solution? 55 Guideline: Proxy, Load Balancer, or API Gateway 56 vi | Table of Contents

📄 Page 9

Case Study: Exposing the Attendee Service to Consumers 57 What Is an API Gateway? 58 What Functionality Does an API Gateway Provide? 58 Where Is an API Gateway Deployed? 59 How Does an API Gateway Integrate with Other Technologies at the Edge? 60 Why Use an API Gateway? 61 Reduce Coupling: Adapter/Facade Between Frontends and Backends 62 Simplify Consumption: Aggregating/Translating Backend Services 63 Protect APIs from Overuse and Abuse: Threat Detection and Mitigation 64 Understand How APIs Are Being Consumed: Observability 65 Manage APIs as Products: API Lifecycle Management 66 Monetize APIs: Account Management, Billing, and Payment 68 A Modern History of API Gateways 68 1990s Onward: Hardware Load Balancers 68 Early 2000s Onward: Software Load Balancers 69 Mid-2000s: Application Delivery Controllers (ADCs) 70 Early 2010s: First-Generation API Gateways 71 2015 Onward: Second-Generation API Gateways 72 Current API Gateway Taxonomy 73 Traditional Enterprise Gateways 73 Microservices/Micro Gateways 73 Service Mesh Gateways 74 Comparing API Gateway Types 74 Case Study: Evolving the Conference System Using an API Gateway 75 Installing Ambassador Edge Stack in Kubernetes 76 Configuring Mappings from URL Paths to Backend Services 77 Configuring Mappings Using Host-based Routing 78 Deploying API Gateways: Understanding and Managing Failure 79 API Gateway as a Single Point of Failure 79 Detecting and Owning Problems 79 Resolving Incidents and Issues 80 Mitigating Risks 80 Common API Gateway Implementation Pitfalls 81 API Gateway Loopback 81 API Gateway as an ESB 82 Turtles (API Gateways) All the Way Down 82 Selecting an API Gateway 83 Identifying Requirements 83 Build Versus Buy 83 ADR Guideline: Selecting an API Gateway 84 Summary 85 Table of Contents | vii

📄 Page 10

4. Service Mesh: Service-to-Service Traffic Management. . . . . . . . . . . . . . . . . . . . . . . . . . 87 Is Service Mesh the Only Solution? 87 Guideline: Should You Adopt Service Mesh? 88 Case Study: Extracting Sessions Functionality to a Service 88 What Is Service Mesh? 90 What Functionality Does a Service Mesh Provide? 92 Where Is a Service Mesh Deployed? 93 How Does a Service Mesh Integrate with Other Networking Technologies? 94 Why Use a Service Mesh? 96 Fine-grained Control of Routing, Reliability, and Traffic Management 96 Provide Transparent Observability 99 Enforce Security: Transport Security, Authentication, and Authorization 100 Supporting Cross-Functional Communication Across Languages 100 Separating Ingress and Service-to-Service Traffic Management 101 Evolution of Service Mesh 102 Early History and Motivations 103 Implementation Patterns 104 Service Mesh Taxonomy 111 Case Study: Using a Service Mesh for Routing, Observability, and Security 111 Routing with Istio 112 Observing Traffic with Linkerd 113 Network Segmentation with Consul 115 Deploying a Service Mesh: Understanding and Managing Failure 118 Service Mesh as a Single Point of Failure 118 Common Service Mesh Implementation Challenges 118 Service Mesh as ESB 118 Service Mesh as Gateway 119 Too Many Networking Layers 119 Selecting a Service Mesh 119 Identifying Requirements 119 Build Versus Buy 120 Checklist: Selecting a Service Mesh 120 Summary 121 Part III. API Operations and Security 5. Deploying and Releasing APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Separating Deployment and Release 126 Case Study: Feature Flagging 126 Traffic Management 128 Case Study: Modeling Releases in the Conference System 129 API Lifecycle 129 viii | Table of Contents

📄 Page 11

Mapping Release Strategies to Lifecycle 130 ADR Guideline: Separating Release from Deployment with Traffic Management and Feature Flags 131 Release Strategies 131 Canary Releases 131 Traffic Mirroring 133 Blue-Green 134 Case Study: Performing Rollouts with Argo Rollouts 135 Monitoring for Success and Identifying Failure 139 Three Pillars of Observability 139 Important Metrics for APIs 140 Reading the Signals 141 Application Decisions for Effective Software Releases 142 Response Caching 142 Application-Level Header Propagation 142 Logging to Assist Debugging 143 Considering an Opinionated Platform 143 ADR Guideline: Opinionated Platforms 143 Summary 144 6. Operational Security: Threat Modeling for APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Case Study: Applying OWASP to the Attendee API 146 The Risk of Not Securing External APIs 147 Threat Modeling 101 148 Thinking Like an Attacker 149 How to Threat Model 149 Step 1: Identify Your Objectives 150 Step 2: Gather the Right Information 150 Step 3: Decompose the System 151 Step 4: Identify Threats—Taking This in Your STRIDE 151 Step 5: Evaluate Threat Risks 162 Step 6: Validation 165 Summary 165 7. API Authentication and Authorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Authentication 167 End-User Authentication with Tokens 169 System-to-System Authentication 170 Why You Shouldn’t Mix Keys and Users 171 OAuth2 171 Authorization Server Role with API Interactions 172 JSON Web Tokens (JWT) 173 Terminology and Mechanisms of OAuth2 Grants 175 Table of Contents | ix

📄 Page 12

ADR Guideline: Should I Consider Using OAuth2? 176 Authorization Code Grant 177 Refresh Tokens 181 Client Credentials Grant 181 Additional OAuth2 Grants 182 ADR Guideline: Choosing Which OAuth2 Grants to Support 183 OAuth2 Scopes 183 Authorization Enforcement 185 Introducing OIDC 186 SAML 2.0 187 Summary 188 Part IV. Evolutionary Architecture with APIs 8. Redesigning Applications to API-Driven Architectures. . . . . . . . . . . . . . . . . . . . . . . . . 191 Why Use APIs to Evolve a System? 192 Creating Useful Abstractions: Increasing Cohesion 192 Clarifying Domain Boundaries: Promoting Loose Coupling 194 Case Study: Establishing Attendee Domain Boundaries 194 End State Architecture Options 195 Monolith 195 Service-Oriented Architecture (SOA) 196 Microservices 196 Functions 197 Managing the Evolutionary Process 197 Determine Your Goals 197 Using Fitness Functions 198 Decomposing a System into Modules 199 Creating APIs as “Seams” for Extension 201 Identifying Change Leverage Points within a System 202 Continuous Delivery and Verification 202 Architectural Patterns for Evolving Systems with APIs 202 Strangler Fig 203 Facade and Adapter 204 API Layer Cake 205 Identifying Pain Points and Opportunities 205 Upgrade and Maintenance Issues 205 Performance Issues 206 Breaking Dependencies: Highly Coupled APIs 206 Summary 207 x | Table of Contents

📄 Page 13

9. Using API Infrastructure to Evolve Toward Cloud Platforms. . . . . . . . . . . . . . . . . . . . . 209 Case Study: Moving the Attendee Service to the Cloud 210 Choosing a Cloud Migration Strategy 211 Retain or Revisit 211 Rehost 212 Replatform 213 Repurchase 213 Refactor/Re-architect 213 Retire 214 Case Study: Replatforming the Attendee Service to the Cloud 214 Role of API Management 215 North–South Versus East–West: Blurring Lines of Traffic Management 216 Start at the Edge and Work Inward 216 Crossing Boundaries: Routing Across Networks 217 From Zonal Architecture to Zero Trust 217 Getting in the Zone 217 Trust No One and Verify 219 Role of Service Mesh in Zero Trust Architectures 220 Summary 223 10. Wrap-up. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Case Study: A Look Back on Your Journey 225 APIs, Conway’s Law, and Your Organization 232 Understanding Decision Types 233 Preparing for the Future 233 Async Communication 234 HTTP/3 234 Platform-based Mesh 234 What’s Next: How to Keep Learning About API Architecture 235 Continually Honing the Fundamentals 235 Keeping Up-to-Date with Industry News 235 Radars, Quadrants, and Trend Reports 236 Learning About Best Practices and Use Cases 236 Learning by Doing 237 Learning by Teaching 237 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 Table of Contents | xi

📄 Page 14

(This page has no text content)

📄 Page 15

Foreword When I built my first APIs at the Financial Times, over a decade ago, there weren’t too many of them. We were building on a monolithic architecture, and the APIs were solely there for external third parties to get access to our content. Now though, APIs are everywhere and they are core to your success when building a system. That’s because, over the last decade, a couple of things have combined to change the way many of us do software development. Firstly, the technology available for us changed. The rise of cloud computing gave us self-service, on-demand provisioning. Automated build and deployment pipelines allowed us to do continuous integration and deployment, and containers and associ‐ ated technologies like orchestration let us run large numbers of small, independent services as a distributed system. Why are we doing that? Because of the second thing: the research showing that successful software development organizations have loosely coupled architectures and autonomous, empowered teams. Successful here is defined in terms of a positive impact on the business: increased market share, productivity, and profitability. Our architectures now tend to be more loosely coupled, distributed, and built around APIs. You want your APIs to be discoverable, consistent, and unlikely to cause problems to the consumers even if they change unexpectedly or disappear. Anything else will couple work together and slow down your teams. In this book, James, Daniel and Matthew provide a comprehensive and practical guide to building effective API architectures. They cover a lot of ground, from how to build and test an individual API, through the ecosystem you deploy them into, the ways to release and operate them effectively, and perhaps most importantly, how to use APIs to evolve your architecture. Those first APIs I built at the Financial Times don’t exist anymore, and we built those systems again from scratch. That’s xiii

📄 Page 16

costly. James, Daniel, and Matthew provide a template for how to deal with inevitable change and evolve your systems, using APIs as a key tool. Software architecture has been defined as those decisions that are both important and hard to change. These are the decisions that will make your project succeed—or fail. The authors’ focus is not on architecture in the abstract, but on how you apply architecture within your own organizations. Deciding to adopt an API gateway or a service mesh, and which one, is exactly the kind of hard-to-undo decision that you should approach with caution and evaluate carefully. James, Daniel, and Matthew give strong, opinionated guidance where they feel it is appropriate, and where the options are less clearcut, they provide a framework to help you make the best choice for your circumstances. They illustrate throughout with a practical and realistic case study that takes the concepts and shows how you actually make them work in practice. Their case study evolves throughout the book, in the same way real systems do. The authors show that you don’t have to do everything upfront; you can evolve your architecture piece by piece, extracting services and adding tools like API gateways and service meshes as you find you need them. When I built my first APIs, I made a lot of mistakes. I wish I’d had a book like this, to help me understand where I might trip up, and to guide me towards sensible decisions. I recommend this book to anyone leading work on systems where APIs play a major role. With it, you should be able to develop a consistent set of tools and standards to support every team building APIs in your organization. — Sarah Wells, Co-Chair of the QCon London conference, independent consultant, and former Technical Director at the Financial Times, Reading, UK, September 2022 xiv | Foreword

📄 Page 17

Preface Why Did We Write This Book? In early 2020 we attended O’Reilly Software Architecture in New York, where Jim and Matt gave a workshop on APIs and a presentation on API gateways. Jim and Daniel know each other from the London Java Community, and like at many architecture events, we got together to talk about our thoughts and understanding around API architectures. As we were talking on the hallway track, several conference delegates came up to us and chatted about their experiences with APIs. People were asking for our thoughts and guidance on their API journey. It was at this point that we thought writing a book on the topic of APIs would help share our discussions from conferences with other architects. Why Should You Read This Book? This book has been designed to provide a complete picture on designing, operating, and evolving an API architecture. We have shared our experience and advice through both our writing and an accompanying case study that mimics a real-life event- management conference system that enables attendees to view and book presentation sessions. The case study runs throughout the book, with the goal of you exploring how abstract concepts sometimes translate into practical application. If you want a high-level overview of the evolution of the case study, you can find this in Chapter 10. We also believe in allowing you to make your own decisions. To support this, we will: • Be clear when we have a strong recommendation or guidance. • Highlight areas of caution and problems that you may encounter. xv

📄 Page 18

1 You will learn more about ADRs and their importance to making and documenting architectural decisions in the Introduction. • Supply an Architecture Decision Record (ADR) Guideline1 to help inform the best possible decision given the circumstances of your architecture and provide guidance on what to consider (because sometimes the answer is “it depends”). • Highlight references and useful articles where you can find more in-depth content. The book is not just a greenfield technology book. We felt that covering existing architectures with an evolutionary approach toward more suitable API architectures would provide the most benefit for you. We also tried to balance this with looking forward to newer technologies and developments in the API architecture domain. Who This Book Is For Although we had an initial persona in mind when creating this book, during the writ‐ ing and reviewing process three key personas emerged: the developer, an accidental architect, and the solutions or enterprise architect. We have outlined these personas in the following sections, with the aim that you not only identify with at least one of them, but also so that you can look at each chapter through the different lens these personas provide. Developer You have most likely been coding professionally for several years and have a good understanding of common software development challenges, patterns, and best practices. You are increasingly realizing that the software industry’s march toward building service-oriented architecture (SOA) and adopting cloud services means that building and operating APIs is fast becoming a core skill. You are keen to learn more about designing effective APIs and testing them. You want to explore the various implementation choices (e.g., synchronous versus asynchronous communica‐ tion) and technologies and learn how to ask the right questions and evaluate which approach is best for a given context. Accidental Architect You have most likely been developing software for many years and have often operated as a team lead or resident software architect (even if you don’t have the official titles). You understand core architectural concepts, such as designing for high cohesion and loose coupling, and apply these to all aspects of software development, including design, testing, and operating systems. xvi | Preface

📄 Page 19

You realize that your role is increasingly focused on combining systems to meet cus‐ tomer requirements. This could include internally built applications and third-party SaaS-type offerings. APIs play a big part in successfully integrating your systems with external systems. You want to learn more about the supporting technologies (e.g., API gateway, service mesh, etc.) and also understand how to operate and secure API-based systems. Solutions/Enterprise Architect You have been designing and building enterprise software systems for several years and most likely have the word architect in your job title or role description. You are responsible for the big picture of software delivery and typically work within the context of a large organization or a series of large interconnected organizations. You recognize the changes that the latest iteration of service-based architectural styles are having on the design, integration, and governance of software, and you see APIs are pivotal to the success of your organization’s software strategy. You are keen to learn more about evolutionary patterns and understand how the choice of API design and implementation will impact this. You also want to focus on the cross-functional “ilities”—usability, maintainability, scalability, and availability—and understand how to build API-based systems that exhibit such properties, as well as provide security. What You Will Learn After reading this book you will understand: • The fundamentals of REST APIs and how to best build, version, and test APIs • The architectural patterns involved in building an API platform • The differences in managing API traffic at ingress and within service-to-service communication, and how to apply patterns and technologies such as API gate‐ ways and service meshes • Threat modeling and key security considerations for APIs, such as authentica‐ tion, authorization, and encryption • How to evolve existing systems toward APIs and different target deployments, such as the cloud And you will be able to: • Design, build, and test API-based systems • Help to implement and drive an organization’s API program from an architec‐ tural perspective • Deploy, release, and configure key components of an API platform Preface | xvii

📄 Page 20

• Deploy gateways and service meshes based on case studies • Identify vulnerabilities in API architecture and implement measured security mitigations • Contribute to emerging API trends and the associated communities What This Book Is Not We realize that APIs encompass a vast market space and we want to be clear what this book will not cover. That doesn’t mean to say that we believe these topics are not important; however, if we tried to cover everything we wouldn’t be able to share our knowledge effectively with you. We will cover application patterns for migration and modernization that will include taking advantage of cloud platforms, but the book is not wholly focused on cloud technologies. Many of you will have hybrid architectures or even have all of your systems hosted in data centers. We want to ensure that we cover the design and operational factors of API architectures that support both approaches. The book is not tied to a specific language but will use some lightweight examples to demonstrate approaches to building/designing APIs and their corresponding infra‐ structure. The book will focus more on the approach, and code examples will be available in the accompanying GitHub repository. The book does not favor one style of architecture over another, however we will discuss situations in which architectural approaches may cause limitations to the API offer‐ ing presented. Conventions Used in This Book The following typographical conventions are used in this book: Italic Indicates new terms, URLs, email addresses, filenames, and file extensions. Constant width Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. Constant width bold Shows commands or other text that should be typed literally by the user. Constant width italic Shows text that should be replaced with user-supplied values or by values deter‐ mined by context. xviii | Preface