Learning API Styles: Understanding the Trade-Offs of Common APIs and Choosing the Correct Solutions

Cover....1

Copyright....6

Table of Contents....7

Foreword....13

Preface....15

Why We Wrote This Book....16

Who Should Read This Book....16

What’s in This Book....17

What’s Not in This Book....17

Weather Forecast Service....17

Conventions Used in This Book....24

Using Code Examples....24

O’Reilly Online Learning....25

How to Contact Us....25

Acknowledgments....26

Acknowledgments from Lukasz Dynowski....26

Acknowledgments from Marcin Dulak....27

Chapter 1. API Concepts....29

What Is an API?....29

Network-Based APIs....31

Concepts of API Communication....34

Message....34

Transmission Modes....35

Synchronous and Asynchronous Communication Types....37

History of APIs....38

Why APIs?....41

What Are API Styles?....43

API as a Product....47

API Lifecycle....49

Planning....50

Design....52

Implementation....53

Testing....54

Deployment....58

Maintenance....61

Retirement....62

API Governance, Management, and Platform....64

Future of APIs....65

Summary....67

Chapter 2. API Design Patterns....69

Examples of API Design Patterns....69

API Language....70

API Naming....70

Evolving APIs....73

API Versioning....75

Encoding....78

Filtering....85

Counting and Sorting....86

Pagination....87

Long-Running Tasks....90

Request Deduplication....91

Request Retry....91

Rate Limiting....93

Caching....94

Deletion....95

API Security....96

OWASP Top 10 API Security....97

Examples of API Security Patterns....98

Encryption, Authentication, and Authorization....98

Sanitization and Validation....99

Scraping Mitigation....100

API Design Best Practices....101

Summary....104

Chapter 3. Network....105

Network Protocols....105

Socket API....106

TCP/IP and the OSI Model....108

Implementing TCP ECHO Service....111

Network Lab Setup....112

TCP ECHO Service....114

TCP ECHO Server....117

TCP ECHO Client with Netcat....118

TCP ECHO Client with Scapy....121

Security....123

TCP ECHO Client with OpenSSL....124

Exercises....130

Summary....131

Chapter 4. Web Protocols....133

What Is Hypertext?....133

HTTP Lab Setup....135

HTTP/0.9....136

HTTP and HTML in Action....137

HTTP/1.0....140

HTTP Message Headers and Body....141

HTTP in a Browser....144

How DNS Affects Browser Connections....145

Parallel TCP Connections in a Browser....147

Limitations of TCP....150

TCP Head-of-Line Blocking....150

TCP Slow Start and Congestion Avoidance....155

HTTP/1.1....156

HTTP Connection Persistence....158

HTTP/2....161

HTTP/2 Frames and Streams....163

HTTP/3....167

QUIC 1-RTT Connection Establishment....171

Exercises....176

Summary....177

Chapter 5. REST....179

HTTP, Resource, and URI....179

Client-Server Communication....182

Origins of REST....185

API Maturity Models....187

RESTful, RESTless, or REST....188

Is Being RESTless Good Enough?....190

Implementation....192

API Endpoints....193

API Versioning....194

CRUD....195

Pagination....206

Rate Limiting....208

Caching....209

Security....210

JSON Web Token....211

Transport Layer Security....215

Documentation....216

OpenAPI Specification....217

Three Approaches to API Specification....220

Trade-Offs....222

When to Use REST....223

Exercises....224

Summary....224

Chapter 6. GraphQL....225

Problems with REST....226

Thinking in Graphs....226

Origins of GraphQL....228

GraphQL Versus REST....228

GraphQL Constructs....229

How GraphQL Works....231

Implementation....232

GraphiQL....232

Executing Mutations....234

CRUD....236

Read....236

Create, Update, Delete....241

Security....244

Attacking GraphQL....244

Authentication....247

Documentation....249

Trade-Offs....250

When to Use GraphQL....253

Exercises....253

Summary....253

Chapter 7. Web Feeds....255

What Is a Web Feed?....255

Why Web Feeds?....256

Evolution of Web Feeds....257

What Is Atom Feed?....259

Implementation....261

Reading Feeds....264

Security....266

Trade-Offs....267

Exercises....268

Summary....269

Chapter 8. gRPC....271

Remote Procedure Call....272

Origins of gRPC....272

Protobuf Serialization....273

Code Generation....278

gRPC ECHO Server and Client....281

The Four RPC Types....286

Protobuf Wire Format....290

Implementation....294

gRPC Atom Feed Enricher Service....295

Security....304

Documentation....305

Trade-Offs....306

When to Use gRPC....308

Exercises....309

Summary....309

Chapter 9. Webhooks....311

What Are Webhooks?....312

Origins of Webhooks....313

Incoming and Outgoing Webhooks....313

Integration and Data Flow....314

Implementation....316

Security....319

Documentation....323

Trade-Offs....326

When to Use Webhooks....329

Exercises....329

Summary....330

Chapter 10. WebSocket....331

WebSocket and WebSocket API....332

WebSocket Opening Handshake....333

Implementation....338

WebSocket ECHO Client and Server....338

WebSocket Protocol....340

WebSocket Weather Alert Server....341

WebSocket Weather Alert Client....349

Security....350

Origin Validation....350

Trusted Host Security....351

JSON Web Token....351

Transport Layer Security....353

Documentation....354

Trade-Offs....358

When to Use WebSocket....361

Exercises....361

Summary....362

Chapter 11. Messaging....363

What Is Messaging?....364

What Is a Queue?....367

Messaging Patterns....369

Work Queue Pattern....369

Publish-Subscribe Pattern....370

Routing Pattern....370

Topics Pattern....371

Request-Response Pattern....372

Implementation....373

Work Queue....373

Security....383

Unencrypted Messages in Transit....384

Messages Encrypted in Transit....385

Authentication and Authorization....388

Documentation....391

AsyncAPI Specification....392

AsyncAPI Documentation....394

Message Versioning....396

Trade-Offs....397

When to Use Messaging....400

Exercises....401

Summary....402

Index....403

About the Authors....414

Colophon....414

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

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

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