Learning API Styles Understanding the Trade-Offs of Common APIs and Choosing the Correct Solutions (Lukasz Dynowski, Marcin Dulak) (Z-Library)

📄 File Format: PDF

💾 File Size: 16.0 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

Learning API Styles Understanding the Trade-Offs of Common APIs and Choosing the Correct Solutions Lukasz Dynowski & Marcin Dulak Foreword by Jacqui Read

📄 Page 2

ISBN: 978-1-098-15399-1 US $69.99 CAN $87.99 SOF T WARE DEVELOPMENT Lukasz Dynowski is an independent consultant with over a decade of experience in IT, specializing in high-performance computing and holding roles such as full stack developer, DevOps engineer, and software architect. Marcin Dulak has over two decades of experience in IT, most recently specializing in on-premises and cloud infrastructure for web and data applications. An application programming interface (API) enables data exchange in systems such as web applications, microservices, and IoT devices. In this hands-on book, authors Lukasz Dynowski and Marcin Dulak show software developers and architects how to design and implement REST, GraphQL, gRPC, webhooks, WebSocket, messaging APIs, and more. This book looks at the most popular API styles from a network, application, and architecture perspective. You’ll learn how to determine the appropriate type of API for your application use case and how to tackle design decisions along the way. You’ll also learn the trade-offs between various APIs and acquire practical knowledge of how to implement them. • Explore the origins and evolution of API styles • Learn network protocols that various APIs use • Understand the trade-offs of each API style • Select an appropriate API style • Learn how to implement, secure, and document the APIs Learning API Styles “Learning API Styles is a must-read for anyone serious about building robust, scalable APIs. From defining APIs and various API design patterns to identifying the trade-offs of the many API communication methods available, this masterful guide contains all you need to know about API design and development.” Mark Richards, coauthor of Fundamentals of Software Architecture “This book is a must-have for any developer aiming to understand API fundamentals and make more informed design decisions for reliable systems.” William Jamir Silva, senior software engineer

📄 Page 3

Praise for Learning API Styles Learning API Styles is a must-read for anyone serious about building robust, scalable APIs. From defining APIs and various API design patterns to identifying the trade-offs of the many API communication methods available, this masterful guide contains all you need to know about API design and development. —Mark Richards, coauthor of Fundamentals of Software Architecture This book offers an indispensable exploration of modern API development, from low-level protocols to advanced designs. It’s a must-have for any developer aiming to understand API fundamentals and make more informed design decisions for reliable systems. —William Jamir Silva, senior software engineer This book explores the technical underpinnings, the architectural decision points, and the implementation details that a modern developer will need to know to design and implement a web API. —Eric Potter, director of Technical Education This book provides valuable insights and practical guidance for building and using common API technologies for both beginners and experienced practitioners. —Karandeep Johar, software engineering manager, Amplitude

📄 Page 4

(This page has no text content)

📄 Page 5

Lukasz Dynowski and Marcin Dulak Foreword by Jacqui Read Learning API Styles Understanding the Trade-Offs of Common APIs and Choosing the Correct Solutions

📄 Page 6

978-1-098-15399-1 [LSI] Learning API Styles by Lukasz Dynowski and Marcin Dulak Copyright © 2025 SRP Consultancy and Marcin Dulak. 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 (https://oreilly.com). For more information, contact our corporate/institu‐ tional sales department: 800-998-9938 or corporate@oreilly.com. Acquisitions Editor: Louise Corrigan Indexer: BIM Creatives, LLC Development Editor: Michele Cronin Cover Designer: Karen Montgomery Production Editor: Clare Laylock Cover Illustrator: Karen Montgomery Copyeditor: Krsta Technology Solutions Interior Designer: David Futato Proofreader: Sharon Wilkey Interior Illustrator: Kate Dullea July 2025: First Edition Revision History for the First Edition 2025-07-11: First Release See https://oreilly.com/catalog/errata.csp?isbn=9781098153991 for release details. The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Learning API Styles, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. The views expressed in this work are those of the authors and do not represent the publisher’s views. 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 7

Table of Contents Foreword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii 1. API Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 What Is an API? 1 Network-Based APIs 3 Concepts of API Communication 6 Message 6 Transmission Modes 7 Synchronous and Asynchronous Communication Types 9 History of APIs 10 Why APIs? 13 What Are API Styles? 15 API as a Product 19 API Lifecycle 21 Planning 22 Design 24 Implementation 25 Testing 26 Deployment 30 Maintenance 33 Retirement 34 API Governance, Management, and Platform 36 Future of APIs 37 Summary 39 v

📄 Page 8

2. API Design Patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Examples of API Design Patterns 41 API Language 42 API Naming 42 Evolving APIs 45 API Versioning 47 Encoding 50 Filtering 57 Counting and Sorting 58 Pagination 59 Long-Running Tasks 62 Request Deduplication 63 Request Retry 63 Rate Limiting 65 Caching 66 Deletion 67 API Security 68 OWASP Top 10 API Security 69 Examples of API Security Patterns 70 Encryption, Authentication, and Authorization 70 Sanitization and Validation 71 Scraping Mitigation 72 API Design Best Practices 73 Summary 76 3. Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Network Protocols 77 Socket API 78 TCP/IP and the OSI Model 80 Implementing TCP ECHO Service 83 Network Lab Setup 84 TCP ECHO Service 86 TCP ECHO Server 89 TCP ECHO Client with Netcat 90 TCP ECHO Client with Scapy 93 Security 95 TCP ECHO Client with OpenSSL 96 Exercises 102 Summary 103 vi | Table of Contents

📄 Page 9

4. Web Protocols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 What Is Hypertext? 105 HTTP Lab Setup 107 HTTP/0.9 108 HTTP and HTML in Action 109 HTTP/1.0 112 HTTP Message Headers and Body 113 HTTP in a Browser 116 How DNS Affects Browser Connections 117 Parallel TCP Connections in a Browser 119 Limitations of TCP 122 TCP Head-of-Line Blocking 122 TCP Slow Start and Congestion Avoidance 127 HTTP/1.1 128 HTTP Connection Persistence 130 HTTP/2 133 HTTP/2 Frames and Streams 135 HTTP/3 139 QUIC 1-RTT Connection Establishment 143 Exercises 148 Summary 149 5. REST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 HTTP, Resource, and URI 151 Client-Server Communication 154 Origins of REST 157 API Maturity Models 159 RESTful, RESTless, or REST 160 Is Being RESTless Good Enough? 162 Implementation 164 API Endpoints 165 API Versioning 166 CRUD 167 Pagination 178 Rate Limiting 180 Caching 181 Security 182 JSON Web Token 183 Transport Layer Security 187 Documentation 188 OpenAPI Specification 189 Table of Contents | vii

📄 Page 10

Three Approaches to API Specification 192 Trade-Offs 194 When to Use REST 195 Exercises 196 Summary 196 6. GraphQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Problems with REST 198 Thinking in Graphs 198 Origins of GraphQL 200 GraphQL Versus REST 200 GraphQL Constructs 201 How GraphQL Works 203 Implementation 204 GraphiQL 204 Executing Mutations 206 CRUD 208 Read 208 Create, Update, Delete 213 Security 216 Attacking GraphQL 216 Authentication 219 Documentation 221 Trade-Offs 222 When to Use GraphQL 225 Exercises 225 Summary 225 7. Web Feeds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 What Is a Web Feed? 227 Why Web Feeds? 228 Evolution of Web Feeds 229 What Is Atom Feed? 231 Implementation 233 Reading Feeds 236 Security 238 Trade-Offs 239 Exercises 240 Summary 241 viii | Table of Contents

📄 Page 11

8. gRPC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Remote Procedure Call 244 Origins of gRPC 244 Protobuf Serialization 245 Code Generation 250 gRPC ECHO Server and Client 253 The Four RPC Types 258 Protobuf Wire Format 262 Implementation 266 gRPC Atom Feed Enricher Service 267 Security 276 Documentation 277 Trade-Offs 278 When to Use gRPC 280 Exercises 281 Summary 281 9. Webhooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 What Are Webhooks? 284 Origins of Webhooks 285 Incoming and Outgoing Webhooks 285 Integration and Data Flow 286 Implementation 288 Security 291 Documentation 295 Trade-Offs 298 When to Use Webhooks 301 Exercises 301 Summary 302 10. WebSocket. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 WebSocket and WebSocket API 304 WebSocket Opening Handshake 305 Implementation 310 WebSocket ECHO Client and Server 310 WebSocket Protocol 312 WebSocket Weather Alert Server 313 WebSocket Weather Alert Client 321 Security 322 Origin Validation 322 Trusted Host Security 323 Table of Contents | ix

📄 Page 12

JSON Web Token 323 Transport Layer Security 325 Documentation 326 Trade-Offs 330 When to Use WebSocket 333 Exercises 333 Summary 334 11. Messaging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 What Is Messaging? 336 What Is a Queue? 339 Messaging Patterns 341 Work Queue Pattern 341 Publish-Subscribe Pattern 342 Routing Pattern 342 Topics Pattern 343 Request-Response Pattern 344 Implementation 345 Work Queue 345 Security 355 Unencrypted Messages in Transit 356 Messages Encrypted in Transit 357 Authentication and Authorization 360 Documentation 363 AsyncAPI Specification 364 AsyncAPI Documentation 366 Message Versioning 368 Trade-Offs 369 When to Use Messaging 372 Exercises 373 Summary 374 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 x | Table of Contents

📄 Page 13

Foreword A software system is not just the definition of its parts but how those parts communi‐ cate. The quality of that communication is a huge factor in the system’s overall per‐ formance. Your communication methods, such as APIs, need to be thoughtfully constructed and governed, built on strong foundations. This is where Learning API Styles comes in. Not only is the content of the book immensely valuable, the way it is structured enables easy and efficient learning. Learning API Styles starts with important foundational knowledge, an appreciation of API concepts (Chapter 1), including the API lifecycle. Chapter 2, on API design pat‐ terns, should be a prerequisite for anyone involved in the design and implementation of any API. Network protocols (Chapter 3) are then built upon with explanations of web protocols (Chapter 4), before introducing the API styles (beginning in Chap‐ ter 5) which are based on those protocols. A hugely important concept for APIs runs throughout this book: security. Lukasz and Marcin say in Chapter 1 that “We perceive security as a force that is present in all phases of the API lifecycle,” and I couldn’t agree more. An API without security, con‐ sidered at every stage, provides an easy and tempting target for bad actors. Look at the news, and you’ll see a state government that has allowed anyone access to personal documents, just by knowing a phone number. APIs are the gateways through which numerous businesses lose important data. Carefully designed and implemented security is essential to avoid becoming another newsworthy victim of bad actors. Lukasz and Marcin have woven security into this book like you need to weave it into your API. This book isn’t just theory—it features valuable, practical exercises. You implement the different API styles and, of course, secure them. Practice makes progress. Imple‐ menting the API styles will give you a much more thorough understanding of how the styles work, and also their pros and cons. xi

📄 Page 14

The concepts in this book are vital to understand before designing, architecting, and implementing an API. Here are just a few. Multiple API styles exist because no one size fits all. The trade-offs described for each style in this book will enable you to compare the different styles and to choose the best one for your current context. In Communication Patterns, I talk about considering your audience and their needs. Your API has an audience with needs, whether this is an audience internal or external to your company. The shift from API as glue to API as a product, with an audience and the ability to generate revenue, marked a significant change in how APIs are viewed. The perceived value of APIs increased. This book will enable you and your business to invest effectively in your APIs. An API provides encapsulation: hiding the complexity of data and functionality behind a user-friendly interface. The customer of the API does not need to know how their requests are handled, only how to make the request and what to expect in return. In the same way that you use security to prevent data leaks, you use design to prevent domain concept leaks. The naming and structure of your data and data val‐ ues should match your customers’ expectations. Speak your customer’s language. Do not skip the API naming pattern, or any other design patterns, in Chapter 2. The API lifecycle is a tricky concept, being iterative not sequential. Each phase is linked to all the other phases, all influencing each other with outputs and feedback. You do not need to complete any phase before starting on the next. The API lifecycle is not about big up-front design. Complete enough design to move on to implementa‐ tion, and so on. Vertically slice your API lifecycle to be able to quickly respond to change. The ACED model is a useful reference, along with Chapter 1. Read this book if you want to build a foundation for software systems that communi‐ cate effectively, both internally and with other systems. Get ready to learn API styles from experienced practitioners and start to build your own. — Jacqui Read Author of Communication Patterns Chief architect, The Ministry of Software Design Co-organizer of DDD London Winchester, UK, June 2025 xii | Foreword

📄 Page 15

Preface Whether you realize it or not, the presence of APIs is ubiquitous. Without APIs, your smartphone wouldn’t be able to get the latest weather forecasts, and ground control mission wouldn’t be able to communicate over NASA’s deep space network with the crew, or with active satellites orbiting the Earth. APIs have transformative power, and the finance industry is one example. Nowadays, you don’t have to visit a bank in person to run your errands. You can do most things over the web, using a smartphone (mobile application), or over a phone call. APIs are behind the success of major technological companies like Amazon, Google, Microsoft, OpenAI, Revolut, and Salesforce, generating substantial amounts of reve‐ nue via digital channels. APIs are the veins through which data flows, and some tech‐ nologies like Kubernetes wouldn’t work without them. Application programming interface (API) can have different meanings depending on the context. The term is mainly associated with software, but it can also be applied to hardware. Within the software context, an API can describe a library interface or a network-based API (the most commonly associated term). We define API as an interaction point that allows software components to communi‐ cate. The API provides functionality without exposing the underlying system’s com‐ plexity; it separates system behavior from its implementation details. APIs are primarily used by developers, who programmatically integrate them into the software to enable interoperability within or between systems. The API separates ownership, which allows for better maintenance because what’s behind the API is the responsi‐ bility of the system that exposes it. Over the past decades, we’ve witnessed the rise and expansion of the internet. The internet is a vast, interconnected network of computer systems that allows devices worldwide to communicate with one another. The foundation of this communication is the TCP/IP suite, which acts as the language of the network, enabling applications and devices to exchange information. xiii

📄 Page 16

1 Style is understood as a set of characteristics. See “What Are API Styles?” on page 15 for a summary of the API styles covered in this book. 2 Gartner, “Gartner Predicts More Than 30% of the Increase in Demand for APIs will Come From AI and Tools Using Large Language Models by 2026”, news release, March 20, 2024. This book focuses on network-based APIs, which are a group of APIs that software uses to communicate over the network (typically the internet). An API can be thought of as a shared language (governed by protocols, rules, and conventions) that software applications use to exchange data. Like a human who can speak multiple languages, software can utilize many APIs to communicate. Why We Wrote This Book Throughout our experience, we’ve worked with various APIs, including REST, Query, RPC, broker-based systems, and more. Every API style has an ecosystem sur‐ rounding it: community, working groups, and sometimes internet giants supporting it.1 For every style, you may read many books to discover API merits; and believe us, it takes time to master just one style. Yet we can no longer afford to stick to one API style. Sure, you could go far with REST APIs, but only to a point. This book is a response to a gap we noticed in the IT bookshelves. Namely, recent books on APIs don’t provide a detailed overview of various API styles. Moreover, many books about APIs focus on high-level concepts or offer code snippets without providing complete implementations. The IT industry in the past few years has signaled a need for API skills. In its 2023 “API Trends” report, Gartner mentioned that the top API challenges that organiza‐ tions face were missing key roles, lack of API standards, lack of skills, and security concerns. In 2024, Gartner predicted that 30% of the increase in demand for APIs will come from AI and large language models (LLMs) by 2026.2 This book seeks to address some of the aforementioned API challenges and meet the API needs that the IT industry is lacking. Who Should Read This Book This book is written for software developers and architects who want to know the trade-offs and implementation details of various API styles. Completing this book will give you an understanding of various APIs from the architecture, implementa‐ tion, and network perspective. This book is intended for people who want to do the following: xiv | Preface

📄 Page 17

• Acquire practical skills in designing and implementing APIs securely • Understand the trade-offs (advantages and disadvantages) of API styles • Learn about the protocols that enable data exchange in APIs What’s in This Book In this book, we’ll design and implement synchronous and asynchronous APIs in various styles: REST API (Chapter 5), Query API with GraphQL (Chapter 6), Web Feeds API with the Atom protocol (Chapter 7), RPC API with the gRPC framework (Chapter 8), callback API with webhooks (Chapter 9), bidirectional API with Web‐ Socket (Chapter 10), and broker-based API with RabbitMQ (Chapter 11). Each style has its benefits and drawbacks to be aware of as a developer or architect. We’ll cover the trade-offs of each API style in detail. One additional aspect this book covers, often overlooked, is the role of network protocols in network-based APIs. What’s Not in This Book This book is not intended for a nontechnical audience. If you fall into this category and you’re looking for answers regarding API leadership, strategy, governance, com‐ pliance, and management, then consult APIs: A Strategy Guide by Daniel Jacobson et al. (O’Reilly, 2011) and Continuous API Management by Mehdi Medjaoui et al. (O’Reilly, 2021). Furthermore, this book doesn’t cover topics like API architecture, platforms, and monetization. To learn more about these topics, consult books like Mastering API Architecture by James Gough et al. (O’Reilly, 2022) and API Management: An Archi‐ tect’s Guide to Developing and Managing APIs for Your Organization by Brajesh De (Apress, 2017). Weather Forecast Service To present various API styles, we decided to implement a Weather Forecast Service (WFS). We chose the weather because everyone can intuitively relate to it. Figure P-1 shows an overview of the system, using a C4 context diagram. Preface | xv

📄 Page 18

Figure P-1. Weather Forecast Service (WFS) C4 context diagram The WFS is implemented in the Python programming language, using the Django and Starlette frameworks. WFS provides two types of information: weather forecasts for up to seven days and historical weather records. You could retrieve weather data using REST, GraphQL, and Atom feeds. Besides the weather data, the WFS offers the functionality of weather alerting using WebSocket and weather information enrich‐ ment fetched over gRPC from an LLM. Not all discussed API styles conceptually align with the WFS. As a result, the webhooks and RabbitMQ demo examples aren’t related to WFS. In 2021, GitHub released Codespaces, a cloud-based development environment avail‐ able to any GitHub user for free (as of now). GitHub Codespaces allowed us to create an environment that you can use to execute the examples described in this book. Fur‐ thermore, the environment is Docker-based, which allows you to run the code locally as long as your platform can run Docker containers. xvi | Preface

📄 Page 19

The easiest way to get to work with the code is via GitHub Codespaces. You could also work with code locally, without using GitHub Codespaces, as in Example P-1, later in this preface. GitHub Codespaces is free to use with certain limits, currently a few dozen hours. To stay within the free limit, you have to stop Codespaces after finishing working with it. To work with GitHub Codespaces, you need a GitHub account. If you don’t have one yet, use this signup form to create one. You also need to fork the book’s code repository. Visit https://github.com/ldynia/ learning-api-styles and click the Fork button, as illustrated in Figure P-2. Figure P-2. Book’s code repository and Fork button location Once the repository is forked, the next step is to spin up the environment. For that, you have three options: use a web browser with GitHub Codespaces, use a local inte‐ grated development environment (IDE) that supports GitHub Codespaces, or use Docker on your local machine. The easiest option is to use a web browser. Within the GitHub interface of the forked repository, click the green Code button, then click the Codespaces tab, and last, click the “Create codespace on main” button. If the preceding steps are successfully executed, you’ll have Visual Studio (VS) Code open in the web browser, as shown in Figure P-3. At this point your setup is ready, and you can start executing the code samples included in the book. Preface | xvii

📄 Page 20

Figure P-3. Book’s code repository fork opened remotely in GitHub Codespaces If you choose to interact with GitHub Codespaces using a web browser, we recommend Google Chrome, which may offer the best experience. Another way of using GitHub Codespaces is from an IDE running locally on your machine. The majority of IDEs support GitHub Codespaces. For example, you can use a locally installed version of VS Code. Open VS Code, click the “Open a Remote Window” button (in the lower-left corner), click the “Connect to Codespace” option, and finally, choose the Codespace to which you want to connect. This process is illus‐ trated in Figure P-4. After connecting to GitHub Codespaces, your setup is ready. xviii | Preface