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