The Design of Web APIs

Description

The Design of Web APIs......Page 1 contents......Page 7 foreword......Page 13 preface......Page 15 acknowledgments......Page 17 about this book......Page 19 about the author......Page 23 about the cover illustration......Page 24 Part 1: Fundamentals of API design......Page 25 1 What is API design?......Page 27 1.1.1 An API is a web interface for software......Page 28 1.1.2 APIs turn software into LEGO® bricks......Page 30 1.2.1 A public or private API is an interface for other developers......Page 33 1.2.2 An API is made to hide the implementation......Page 34 1.2.3 The terrible consequences of poorly designed APIs......Page 35 1.3.1 Learning the principles beyond programming interface design......Page 38 1.3.2 Exploring all facets of API design......Page 39 2 Designing an API for its users......Page 41 2.1.1 Focusing on how things work leads to complicated interfaces......Page 42 2.1.2 Focusing on what users can do leads to simple interfaces......Page 44 2.2.1 Viewing an API as software’s control panel......Page 45 2.2.2 Focusing on the consumer’s perspective to create simple APIs......Page 46 2.3 Identifying an API’s goals......Page 48 2.3.1 Identifying the whats and the hows......Page 49 2.3.2 Identifying inputs and outputs......Page 51 2.3.3 Identifying missing goals......Page 52 2.3.4 Identifying all users......Page 55 2.3.5 Using the API goals canvas......Page 56 2.4 Avoiding the provider’s perspective when designing APIs......Page 58 2.4.1 Avoiding data influences......Page 59 2.4.2 Avoiding code and business logic influences......Page 60 2.4.3 Avoiding software architecture influences......Page 62 2.4.4 Avoiding human organization influences......Page 64 2.4.5 Detecting the provider’s perspective in the API goals canvas......Page 65 3 Designing a programming interface......Page 67 3.1.1 Analyzing a REST API call......Page 69 3.1.2 Basic principles of HTTP......Page 71 3.1.3 Basic principles of REST APIs......Page 72 3.2.1 Identifying resources and their relationships with the API goals canvas......Page 73 3.2.2 Identifying actions and their parameters and returns with the API goals canvas......Page 76 3.2.3 Representing resources with paths......Page 78 3.2.4 Representing actions with HTTP......Page 80 3.2.5 REST API and HTTP cheat sheet......Page 84 3.3.1 Designing concepts......Page 86 3.3.2 Designing responses from concepts......Page 89 3.3.3 Designing parameters from concepts or responses......Page 90 3.3.4 Checking parameter data sources......Page 91 3.3.5 Designing other parameters......Page 92 3.4.1 REST trade-off examples......Page 93 3.5 Understanding why REST matters for the design of any API......Page 95 3.5.1 Introducing the REST architectural style......Page 96 3.5.2 The impact of REST constraints on API design......Page 98 4 Describing an API with an API description format......Page 101 4.1 What is an API description format?......Page 102 4.1.1 Introducing the OpenAPI Specification (OAS)......Page 103 4.1.2 Why use an API description format?......Page 105 4.1.3 When to use an API description format......Page 108 4.2.1 Creating an OAS document......Page 109 4.2.2 Describing a resource......Page 110 4.2.3 Describing operations on a resource......Page 111 4.3 Describing API data with OpenAPI and JSON Schema......Page 115 4.3.1 Describing query parameters......Page 116 4.3.2 Describing data with JSON Schema......Page 118 4.3.3 Describing responses......Page 121 4.3.4 Describing body parameters......Page 124 4.4.1 Reusing components......Page 126 4.4.2 Describing path parameters......Page 129 Part 2: Usable API design......Page 133 5 Designing a straightforward API......Page 135 5.1 Designing straightforward representations......Page 136 5.1.1 Choosing crystal-clear names......Page 137 5.1.2 Choosing easy-to-use data types and formats......Page 139 5.1.3 Choosing ready-to-use data......Page 140 5.2 Designing straightforward interactions......Page 142 5.2.1 Requesting straightforward inputs......Page 143 5.2.2 Identifying all possible error feedbacks......Page 145 5.2.3 Returning informative error feedback......Page 146 5.2.4 Returning exhaustive error feedback......Page 150 5.2.5 Returning informative success feedback......Page 152 5.3 Designing straightforward flows......Page 153 5.3.1 Building a straightforward goal chain......Page 155 5.3.2 Preventing errors......Page 156 5.3.3 Aggregating goals......Page 158 5.3.4 Designing stateless flows......Page 159 6 Designing a predictable API......Page 161 6.1 Being consistent......Page 162 6.1.1 Designing consistent data......Page 163 6.1.2 Designing consistent goals......Page 165 6.1.3 The four levels of consistency......Page 166 6.1.4 Copying others: Following common practices and meeting standards......Page 167 6.1.5 Being consistent is hard and must be done wisely......Page 170 6.2.1 Providing and accepting different formats......Page 171 6.2.2 Internationalizing and localizing......Page 175 6.2.3 Filtering, paginating, and sorting......Page 177 6.3 Being discoverable......Page 179 6.3.1 Providing metadata......Page 180 6.3.2 Creating hypermedia APIs......Page 181 6.3.3 Taking advantage of the HTTP protocol......Page 184 7 Designing a concise and well-organized API......Page 186 7.1 Organizing an API......Page 187 7.1.1 Organizing data......Page 188 7.1.2 Organizing feedback......Page 191 7.1.3 Organizing goals......Page 192 7.2 Sizing an API......Page 198 7.2.1 Choosing data granularity......Page 199 7.2.2 Choosing goal granularity......Page 200 7.2.3 Choosing API granularity......Page 202 Part 3: Contextual API design......Page 205 8 Designing a secure API......Page 207 8.1.1 Registering a consumer......Page 209 8.1.2 Getting credentials to consume the API......Page 210 8.1.3 Making an API call......Page 212 8.1.4 Envisioning API design from the perspective of security......Page 213 8.2 Partitioning an API to facilitate access control......Page 215 8.2.1 Defining flexible but complex fine-grained scopes......Page 216 8.2.2 Defining simple but less flexible coarse-grained scopes......Page 219 8.2.3 Choosing scope strategies......Page 221 8.2.4 Defining scopes with the API description format......Page 222 8.3.1 Knowing what data is needed to control access......Page 224 8.3.2 Adapting the design when necessary......Page 225 8.4.1 Handling sensitive data......Page 227 8.4.2 Handling sensitive goals......Page 231 8.4.3 Designing secure error feedback......Page 233 8.4.4 Identifying architecture and protocol issues......Page 235 9 Evolving an API design......Page 237 9.1.1 Avoiding breaking changes in output data......Page 239 9.1.2 Avoiding breaking changes to input data and parameters......Page 244 9.1.3 Avoiding breaking changes in success and error feedback......Page 247 9.1.4 Avoiding breaking changes to goals and flows......Page 249 9.1.5 Avoiding security breaches and breaking changes......Page 250 9.1.6 Being aware of the invisible interface contract......Page 252 9.2 Versioning an API......Page 253 9.2.1 Contrasting API and implementation versioning......Page 254 9.2.2 Choosing an API versioning representation from the consumer’s perspective......Page 256 9.2.3 Choosing API versioning granularity......Page 258 9.2.4 Understanding the impact of API versioning beyond design......Page 262 9.3 Designing APIs with extensibility in mind......Page 263 9.3.1 Designing extensible data......Page 264 9.3.2 Designing extensible interactions......Page 267 9.3.3 Designing extensible flows......Page 268 9.3.4 Designing extensible APIs......Page 269 10 Designing a network‑efficient API......Page 270 10.1 Overview of network communication concerns......Page 271 10.1.1 Setting the scene......Page 272 10.1.2 Analyzing the problems......Page 274 10.2.1 Activating compression and persistent connections......Page 278 10.2.2 Enabling caching and conditional requests......Page 279 10.2.3 Choosing cache policies......Page 282 10.3 Ensuring network communication efficiency at the design level......Page 283 10.3.1 Enabling filtering......Page 284 10.3.2 Choosing relevant data for list representations......Page 286 10.3.3 Aggregating data......Page 288 10.3.4 Proposing different representations......Page 290 10.3.5 Enabling expansion......Page 292 10.3.6 Enabling querying......Page 293 10.3.7 Providing more relevant data and goals......Page 295 10.3.8 Creating different API layers......Page 297 11 Designing an API in context......Page 299 11.1.1 Managing long processes......Page 301 11.1.2 Notifying consumers of events......Page 303 11.1.3 Streaming event flows......Page 305 11.1.4 Processing multiple elements......Page 310 11.2.1 Being aware of consumers' existing practices and limitations......Page 316 11.2.2 Carefully considering the provider’s limitations......Page 320 11.3 Choosing an API style according to the context......Page 323 11.3.1 Contrasting resource-, data-, and function-based APIs......Page 324 11.3.2 Thinking beyond request/response- and HTTP-based APIs......Page 329 12 Documenting an API......Page 330 12.1 Creating reference documentation......Page 332 12.1.1 Documenting data models......Page 334 12.1.2 Documenting goals......Page 337 12.1.3 Documenting security......Page 344 12.1.4 Providing an overview of the API......Page 345 12.1.5 Generating documentation from the implementation: pros and cons......Page 346 12.2 Creating a user guide......Page 347 12.2.1 Documenting use cases......Page 348 12.2.2 Documenting security......Page 350 12.3 Providing adequate information to implementers......Page 351 12.4 Documenting evolutions and retirement......Page 354 13 Growing APIs......Page 358 13.1 The API lifecycle......Page 359 13.2 Building API design guidelines......Page 360 13.2.1 What to put in API design guidelines......Page 361 13.2.2 Continuously building guidelines......Page 364 13.3 Reviewing APIs......Page 366 13.3.1 Challenging and analyzing needs......Page 367 13.3.2 Linting the design......Page 370 13.3.3 Reviewing the design from the provider’s perspective......Page 372 13.3.5 Verifying the implementation......Page 374 13.4 Communicating and sharing......Page 377 index......Page 379