Learning API Styles (for Raymond Rhine) (Lukasz Dynowski, Marcin Dulak) (Z-Library)

📄 File Format: PDF

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

(This page has no text content)

📄 Page 2

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 3

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

📄 Page 4

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/institutional 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

📄 Page 5

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. 978-1-098-15399-1 [LSI]

📄 Page 6

Foreword A software system is not just the definition of its parts but how those parts communicate. The quality of that communication is a huge factor in the system’s overall performance. 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 patterns, 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 Chapter 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, considered 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

📄 Page 7

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. Implementing the API styles will give you a much more thorough understanding of how the styles work, and also their pros and cons. 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 values should match your customers’

📄 Page 8

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 implementation, 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 communicate 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

📄 Page 9

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 revenue via digital channels. APIs are the veins through which data flows, and some technologies 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 communicate. The API provides functionality without exposing the underlying system’s complexity; it separates system behavior from its implementation details. APIs are primarily used by

📄 Page 10

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 responsibility 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. 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 surrounding 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.

📄 Page 11

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 organizations 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, implementation, and network perspective. This book is intended for people who want to do the following: 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

📄 Page 12

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 WebSocket (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, compliance, 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 Architect’s Guide to Developing and Managing APIs for Your Organization by Brajesh De (Apress, 2017).

📄 Page 13

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.

📄 Page 14

(This page has no text content)

📄 Page 15

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 enrichment 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 available 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. Furthermore, the environment is Docker-based, which allows you to run the code locally as long as your platform can run Docker containers. 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. WARNING 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.

📄 Page 16

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 integrated 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.

📄 Page 17

(This page has no text content)

📄 Page 18

Figure P-3. Book’s code repository fork opened remotely in GitHub Codespaces WARNING 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 illustrated in Figure P-4. After connecting to GitHub Codespaces, your setup is ready.

📄 Page 19

(This page has no text content)

📄 Page 20

Figure P-4. Process of connecting to GitHub Codespaces using VS Code If you don’t want to work with GitHub Codespaces, you can run the project locally. You can work with a local copy of the book’s code repository or your fork of it. The local scenario requires manually provisioning your environment with the necessary software. Besides an IDE, you also need Docker and Docker Compose. Example P-1 shows how to clone the book’s code repository. Example P-1. Local clone of book’s code repository git clone https://github.com/ldynia/learning-api-styles code learning-api-styles Clone the book’s code repository. You could also clone your fork. Open the repository with VS Code. After executing the preceding steps for the local setup, you need to start a dev container.3 To do that, follow the steps illustrated in Figure P-5. First, click the “Open a Remote Window” button (in the lower-left corner). Then choose the “Reopen in Container” option; this will build the Docker image and provision the dev container. At this point, your local setup is ready.