The Design of Web APIs

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