index

Please note that index links to approximate location of each term.

Symbols

+json suffix, media type 268

$ref JSON reference property 104, 107

2XX class 167

4XX class 123, 129, 167, 210

5XX class 123, 210

200 OK HTTP 44, 47, 48, 89, 123, 142, 167, 283, 300, 328

201 Created 129, 142, 167, 225, 278, 314

202 Accepted 129, 142, 167, 225, 278

207 Multi-Status 288, 291

301 Moved Permanently 226

304 Not Modified 257

400 Bad Request 123, 127, 132, 167, 210, 225, 288, 315, 352

401 Unauthorized 209

403 Forbidden 123, 127, 209

404 Not Found 47, 123, 167, 209, 226, 288, 300, 328

405 Method Not Allowed 226

406 Not Acceptable 150, 152

409 Conflict 124

410 Gone 145

413 Payload Too Large 167

415 Unsupported Media Type error 150

429 Too many requests 225

500 Internal Server Error 124, 210, 225, 298

503 Service Unavailable 297

A

access control 184

adapting design for 201–202

overview 200–202

partitioning API to facilitate 191–199

coarse-grained scopes 195–197

defining scopes with API description format 198–200

fine-grained scopes 192–194

scope strategies 197–198

access tokens 188

action resources 69

adaptability of design 147–155

content negotiation 148

filtering 153–155

formats 147–151

internationalizing and localizing 151–153

paginating 153–155

sorting 153–155

aggregating data, network communication efficiency 264–267

aggregating goals, for flow of interactions 134–135

analyze phase, API lifecycle 335

API calls

analyzing REST API calls 45–46

security and 188–189

API description format 77–85

defined 78–85

OAS, OpenAPI Specification. (see OAS (OpenAPI Specification))

reasons for using 81–85

API design

facets of 15–16

hiding implementation and 10–11

importance of 9–14

learning principles 14–15

overview 3–16

poor, consequences of 11–14

private APIs 9

public APIs 9

software LEGO® bricks 6–8

API gateway solutions 84

apihandyman.io 47

API layers, network communication efficiency 273

API linting 346, 350

APIs 3, 4

defined 4–8

overview 4–6

API Stylebook 341

API styles 14

application/json media type 78, 80, 98–99, 101–102, 104, 149, 150, 160, 240, 283–284, 295, 317–318, 332

application/pdf 149, 150, 160

application/xml 150, 240, 295

arbitrary scopes 197

array OAS type 98

Authorization header 233

authorization server 187

B

backend API 6, 8, 10

backend applications 6

backend for frontend (BFF) 274, 304

before link, pagination 262

before property, pagination 262

BFF (backend for frontend) 274, 304

body parameters 100–102, 290

boolean property 65, 114– 115

breaking changes, avoiding

in output data 215–220

in success and error feedback 223–225

overview 229

security breaches and 226–228

to goals and flows 225–226

to input data and parameters 220–223

C

cacheability 73

Cache-Control header 257, 259

caching

choosing cache policies 258–259

overview 255–258

client ID 186

client/server separation 73

coarse-grained scope 197

code and business logic influences, avoiding 36–37

code on demand 73, 134

collection resources 51

comma-separated values (CSV) 148, 161, 299

commercial off-the-shelf (COTS) software 293, 295

common practices and standards 143–146

components section, OAS document 103, 106

components.securitySchemes section, OpenAPI document 198, 321

compression 254–255

conditional requests 254–258

consistency of design 138–147

common practices and standards 143–146

data 139–141

goals 141–142

levels of 142–143

usability and 146–147

consumer application 10

consumers 6

adapting design for 292–296

choosing API versioning representation from perspective of 232–234

notifying of events 279–281

reviewing APIs from perspective of 350

software interfaces for 22–24

Content header 295

Content-Language header 152

content negotiation 148

content property, OpenAPI Specification 98

Content-type header 150, 233

Content-type versioning 234

context 275–305

adapting communication to goals and nature of data 277–292

long processes 277–278

notifying consumers of events 279–281

processing multiple elements 286–292

streaming event flows 281–285

choosing API style according to 299–305

data-based APIs 300–304

event-based systems 305

function-based APIs 300–304

resource-based APIs 300–304

full, observing 292–299

consumers’ existing practices and limitations 292–296

provider’s limitations 296–299

Conway’s law 34, 40

COTS (commercial off-the-shelf) software 293, 295

credentials, security 186–188

CRUD functions (create, read, update, delete) 60, 69, 194

CSV (comma-separated values) 148, 161, 299

custom media type 237, 267, 268

vnd prefix, media type 233, 237, 267, 268

+json suffix, media type 268

D

data

aggregating 264–267

consistency of design 139–141

data granularity 175–176

for list representations 262–264

organizing 164–166

security and 203–206

data-based APIs 300–304

data influences, avoiding 36

data types and formats, for representations 115–116

date property 121, 217, 311

DELETE method 58, 145, 160, 298, 352

deprecated flag, OpenAPI Specification 331

description property, OpenAPI Specification 86, 88, 91, 93, 95, 101, 322

design guidelines, API 336–342

continuously building 340–342

overview 337–340

designing for users 17–41

avoiding provider’s perspective 34–41

code and business logic influences 36–37

data influences 36

detecting in API goals canvas 41–42

human organization influences 41–42

software architecture influences 38–39

complicated interfaces 18–20

identifying goals 24–33

simple interfaces 20–21

software interfaces 21–24

API as software control panel 21–22

consumer perspective 22–24

design level, network communication efficiency 259–274

aggregating data 264–267

choosing relevant data for list representations 262–264

creating different API layers 273

enabling expansion 268–269

enabling filtering 260–262

enabling querying 269–271

proposing different representations 266–267

providing more relevant data and goals 271–273

design phase, API lifecycle 336

design process guidelines 337

developer experience (DX) 9

developer portal 185

discoverability 155–161

HTTP 160–161

hypermedia APIs 157–160

providing metadata 156–157

distributed systems 72

documentation 308–333

of evolutions and retirement 330–333

providing adequate information to implementers 327–330

reference documentation 308–323

API overview 321–322

data models 310–313

generating from implementation 322–323

goals 313–320

security 320–321

user guide 323–327

dynamic documentation 327

overview of common behaviors and principles 327

security 326–327

use cases 324–326

download speed 251

DX (developer experience) 9

E

efficiency 73, 111–136, 246–274

empty objects in YAML 86

error feedback

avoiding breaking changes in 223–225

exhaustive 126–128

identifying 121–122

informative 122–126

security and 209–211

error message 289

errors, preventing in flow of interactions 132–134

ETag header 257

event-based systems 305

event flows 281–285

event property, SSE 285

evolution of design 213–245

breaking changes, avoiding

in output data 215–220

in success and error feedback 223–225

overview 229

security breaches and 226–228

to goals and flows 225–226

to input data and parameters 220–223

designing API evolutions 215–229

documenting 330–333

extensibility 239–245

extensible APIs 245

extensible data 240–243

extensible flows 244–245

extensible interactions 243–244

invisible interface contract 228–229

versioning APIs 229–239

choosing versioning representation 232–234

granularity 234–238

understanding impact of 238–239

vs. implementation versioning 230–233

exhaustive error feedback, interactions 126–128

expansion, network communication efficiency 268–269

experience APIs 274

extensibility 239–245

extensible APIs 245

extensible data 240–243

extensible flows 244–245

extensible interactions 243–244

F

fannish folk law 299

feedback

error feedback

avoiding breaking changes in 223–225

exhaustive 126–128

identifying 121–122

informative 122–126

organizing 167–168

success feedback

avoiding breaking changes in 223–225

interactions 128–129

filtering

adaptabiity of design 153–155

network communication efficiency 260–262

flows

avoiding breaking changes in 225–226

usability and straightforwardness of 129–136

aggregating goals 134–135

goal chain 131–132

preventing errors 132–134

stateless flows 135–136

format parameter 148

formats, adaptabiity of design 147–151

functional errors 121

functional limitations 297

function-based APIs 300–304

G

GDPR (General Data Protection Regulation) 204

generic prefix 139

generic suffix 139

GET method 44–45, 47–48, 57, 88, 92, 98, 158, 160, 226, 296, 301

get property, OpenAPI Specification 88

goals, API 24–33

aggregating goals for flow of interactions 134–135

avoiding breaking changes in 225–226

consistency of design 141–142

documenting 313–320

goal chain for flow of interactions 131–132

goal granularity 176–178

goals canvas

detecting provider’s perspective in 41–42

identifying actions and their parameters and returns with 52–54

identifying resources and their relationships with 49–51

overview 32–33

network communication efficiency 271–273

organizing 168–174

security and 207–209

transposing into REST APIs 49–60

Goals column, API goals canvas 32

granularity

of APIs 178–180

of data 175–176

of goals 176–178

versioning APIs and 234–238

GraphQL 269–271, 300–304

grouped errors 168

grouping

properties 165

gRPC 258, 300–304

H

HATEOAS (hypermedia as the engine of the application state) 160

headers map 290

HIPAA (Health Insurance Portability and Accountability Act) 204

How’s column, API goals canvas 32

href property 158, 289

HTTP headers 149

Accept header 267, 283, 295

Accept-Language header 152

Cache-Control header 257, 259

Content header 295

Content-Language header 152

Content-type header 150, 233

ETag header 257

Link header 160

Location header 339

HTTP (HyperText Transfer Protocol) 6, 45, 47, 54, 72, 74, 122, 145, 225, 237, 285

cheat sheet 60

overview 47–48

HTTP method 47

DELETE method 58, 145, 160, 298, 352

GET method 44–45, 47–48, 57, 88, 92, 98, 158, 160, 226, 296, 301

OPTIONS HTTP method 161, 300

PATCH method 59, 70, 301

POST method 47, 56, 60, 70, 78, 89–90, 105, 202, 270, 276, 296

PROPFIND method 289

PROPPATCH method 289

PUT method 60, 301

HTTP status code 46

2XX class 167

4XX class 123, 129, 167, 210

5XX class 123, 210

200 OK HTTP 44, 47, 48, 89, 123, 142, 167, 283, 300, 328

201 Created 129, 142, 167, 225, 278, 314

202 Accepted 129, 142, 167, 225, 278

207 Multi-Status 288, 291

301 Moved Permanently 226

304 Not Modified 257

400 Bad Request 123, 127, 132, 167, 210, 225, 288, 315, 352

401 Unauthorized 209

403 Forbidden 123, 127, 209

404 Not Found 47, 123, 167, 209, 226, 288, 300, 328

405 Method Not Allowed 226

406 Not Acceptable 150, 152

409 Conflict 124

410 Gone 145

413 Payload Too Large 167

415 Unsupported Media Type error 150

429 Too many requests 225

500 Internal Server Error 124, 210, 225, 298

503 Service Unavailable 297

human organization influences, avoiding 41–42

hypermedia APIs 157–160

actions element 157

hypermedia as the engine of the application state (HATEOAS) 160

HyperText Transfer Protocol. See HTTP (HyperText Transfer Protocol)

Hyrum’s law 228

I

id property 240, 288

implementation 5

generating reference documentation from 322–323

versioning 230, 230–233

implementation specifications 307

implement phase, API lifecycle 336

implicit flow 198

info.contact.url, OpenAPI Specification 326

info.description.section, OpenAPI Specification 326, 331

information leak 209

informative error feedback, interactions 122–126

info.section, OpenAPI Specification 321

in property, OpenAPI Specification 93, 106

input data

avoiding breaking changes in 220–223

interactions 119–121

Inputs (source) column, API goals canvas 32

interactions, usability and straightforwardness of 118–129

error feedback

exhaustive 126–128

identifying 121–122

informative 122–126

input data 119–121

success feedback 128–129

interfaces

complicated 18–20

design challenges 69–71

balancing user-friendliness and compliance 71

REST trade-off examples 69–71

REST APIs 45, 48

basic principles of 48

calls, analyzing 45–46

HTTP 47–48

impact of constraints on design 74–76

style overview 72–74

transposing API goals into 49–60

simple 20–21

internationalizing design 151–153

International Telecommunication Union (ITU) 348

invalid parameters 244

invisible interface contract 228–229

IoT (Internet of Things) 305

ISO 639 language codes 151

ISO 3166 country codes 151

ISO 4217 currency codes 144

ISO 7000 graphical symbols for use on equipment 144

items property, list 141, 156, 223, 240–241, 283, 287, 289

items property, OpenAPI Specification 98–99, 104

ITU (International Telecommunication Union) 348

J

java.lang.NullPointerException 210, 216

JSON reference 103

JSON Schema 91, 94–97, 106, 113

L

language parameter 151

latency 251

layered systems 73

learning principles, design 14–15

least privilege principle 192

lifecycle, API 335–336

Link header 160

links property 159

linting 343–348

localizing design 151–153

Location header 339

long processes, managing 277–278

M

malformed request errors 121

mandatory properties 221

Markdown format 318

Maslow’s law 299

media type 98–99, 101, 149–150, 152, 233, 237, 267–268, 284, 288

custom 237, 267–268

vnd prefix, media type 233, 237, 267–268

+json suffix, media type 268

media types

application/json media type 78, 80, 98–99, 101–102, 104, 149–150, 160, 240, 283–284, 295, 317–318, 332

application/pdf 149–150, 160

application/xml 150, 240, 295

text/csv 149–150, 160

text/event-stream media type 283–284

text/plain 240

Message Queuing Telemetry Protocol (MQTP) 305

metadata 156–157, 262

Microsoft Visual Studio Code editor 82

MQTP (Message Queuing Telemetry Protocol) 305

N

names, choosing 113–115

network communication efficiency 246–274

at design level 259–274

aggregating data 264–267

choosing relevant data for list representations 262–264

creating different API layers 273

enabling expansion 268–269

enabling filtering 260–262

enabling querying 269–271

proposing different representations 266–267

providing more relevant data and goals 271–273

at protocol level 254–259

activating compression and persistent connections 254–255

choosing cache policies 258–259

enabling caching and conditional requests 255–258

overview 247–254

nonfunctional requirements 292

non-volatile storage 259

number data type 64, 115, 139, 206

O

OAI (OpenAPI Initiative) 79

OAS (OpenAPI Specification) 78, 85–91, 113, 146, 200

array OAS type 98

API data 91–102

body parameters 100–102

JSON Schema and 94–97

query parameters 92–93

responses 97–100

creating OAS document 85–86

defining scopes with 198–200

describing API resources and actions with 86–87

describing operations on resource 87–91

describing API data 91–102

body parameters 100–102

JSON Schema and 94–97

query parameters 92–93

responses 97–100

array type 98

describing path parameters 105–108

describing resources 86–87

documentation 107

overview 79–81

reusing components 102–105

security

defining scopes with 198–200

oauth2 security type 198

oauth2 security type, OpenAPI Specification 198

OpenAPI Initiative (OAI) 79

OpenAPI Map 81, 107, 312

OpenAPI Specification (OAS). See OAS (OpenAPI Specification)

OpenID Connect 188

Open Web Application Security Project (OWASP) 192

OPTIONS HTTP method 161, 300

organizing APIs 163–174

data 164–166

feedback 167–168

goals 168–174

output data, avoiding breaking changes in 215–220

Output (usage) column, API goals canvas 32

OWASP (Open Web Application Security Project) 192

P

page parameter 153, 261

pageSize parameter 153, 244

paginating 153–155

after property 262

before link 262

before property 262

page parameter 153, 261

pageSize parameter 153, 244

size query parameter 261

parameters, API data

avoiding breaking changes in 220–223

body parameters 100–102

checking parameter data sources 67–68

designing 68–69

path parameters 105–108

query parameters 92–93

parameters property, OpenAPI Specification 92

partitioning API to facilitate access control 191–199

partner APIs 8, 308

PATCH method 59, 70, 287, 301

path parameters 54, 105–108

paths property, OpenAPI Specification 86

PCI DSS (Payment Card Industry Data Security Standard) 204

persistent connections, network communication efficiency 254–255

PlantUML (PUML) 326

portable data types 115

Postel’s law 243

POST method 47, 56, 60, 70, 78, 89–90, 105, 202, 270, 276, 296

predictability of design 137–161

adaptabiity 147–155

filtering 153–155

formats 147–151

internationalizing and localizing 151–153

paginating 153–155

sorting 153–155

consistency 138–147

common practices and standards 143–146

data 139–141

goals 141–142

levels of 142–143

usability and 146–147

discoverability 155–161

HTTP 160–161

hypermedia APIs 157–160

providing metadata 156–157

prefixes 114

private APIs 8–9, 184, 308

PROPFIND method 289

PROPPATCH method 289

ProtoBuf data format 303

protocol level, network communication efficiency 254–259

activating compression and persistent connections 254–255

choosing cache policies 258–259

enabling caching and conditional requests 255–258

provider applications 6, 10

provider-facing documentation 330

provider’s perspective 18, 34–41

adapting design for provider’s limitations 296–299

code and business logic influences 36–37

data influences 36

detecting in API goals canvas 41–42

human organization influences 41–42

reviewing APIs from 348–350

software architecture influences 38–39

public APIs 8–9, 13, 184, 308, 327

publish phase, API lifecycle 336

PUML (PlantUML) 326

PUT method 60, 301

Q

querying, network communication efficiency 269–271

query parameters 57, 68, 92–93, 142, 211, 244

query property, GraphQL 270

R

Range header 154

redoc-cli command-line utility 309

ReDoc 83

reference documentation 308–323

API overview 321–322

data models 310–313

generating from implementation 322–323

goals 313–320

security 320–321

reference guidelines 337

reference property 44, 62, 66, 94, 97

registering consumers 185–186

reliability 73

Remote Procedure Call (RPC) 301

Representational State Transfer (REST). See REST (Representational State Transfer)

representations

network communication efficiency 266–267

usability and straightforwardness of 112–118

data types and formats 115–116

names 113–115

ready-to-use data 116–118

requestBody property, OpenAPI Specification 78, 101

Request For Comments (RFC). See RFC (Request For Comments)

required property, OpenAPI Specification 93, 95

resource-based APIs 300–304

resource expansion 268

resource owner 187

resources 47

resource server 187

resources type 145

response body 46

responses, API data

describing 97–100

designing from concepts 65–66

responses property 88–89

REST APIs 45–48, 74

analyzing REST API calls 45–46

basic principles of 48

HTTP

cheat sheet 60

overview 47–48

impact of constraints on design 74–76

style overview 72–74

transposing API goals into 49–60

API goals canvas 49–54

cheat sheet 60

representing resources with paths 54–56

REST (Representational State Transfer) 44, 72, 75, 76, 160, 277, 300, 303

reusability 73

reusable schema, OpenAPI Specification 103

reviewing APIs 342–353

challenging and analyzing needs 343–344

from consumer’s perspective 350

from provider’s perspective 348–350

linting 346–350

verifying implementation 350–353

RFC 5646 Tags for Identifying Languages 151

RFC 5988 Web Linking 159

RFC 6455 The Websocket Protocol 285

RFC 6749 The OAuth 2.0 Authorization Framework 188

RFC 7231 Hypertext Transfer Protocol 153

RFC (Request For Comments) 123, 129, 146

RPC (Remote Procedure Call) 301

S

scalability 73

Schema Object description, OpenAPI Specification 97

schema property, OpenAPI Specification 93, 318

schemas property, OpenAPI Specification 103

scopes 192, 195, 227

coarse-grained 195–197

defining with API description format 198–200

fine-grained 192–194

strategies 197–198

Secure Sockets Layer (SSL) 188

security 183–211

access control 200–203

adapting design for 201–202

overview 200–202

partitioning API to facilitate 191–199

API calls 188–189

credentials 186–188

documenting 320–321

envisioning API design from perspective of 189–191

handling sensitive material 203–211

identifying architecture and protocol issues 211–212

secure error feedback 209–211

sensitive data 203–206

sensitive goals 207–209

overview 185–191

registering consumers 185–186

security breaches 226, 226–228

user guide 326–327

security, OpenAPI Specification 199

self relationship 159

semantic versioning 231

sensitive data 204

sensitive material 184

server errors 121

Server-Sent Events (SSE) 284, 303, 305

silent breaking change 221, 226

Siren hypermedia format 159

sizing APIs 174–180

API granularity 178–180

data granularity 175–176

goal granularity 176–178

software architecture influences, avoiding 38–39

software interfaces 21–24

consumer’s perspective 22–24

viewing API as software’s control panel 21–22

software LEGO® bricks 6–8

sorting, adaptability of design and 153–155

sort parameter, pagination 155

source (Inputs) column, API goals canvas 32

SSE (Server-Sent Events) 284, 303, 305

SSL (Secure Sockets Layer) 188. See TLS (Transport Layer Security) encryption

standardized HTTP methods 75

standard method 145

stateful flow 136

stateless flows 135–136

statelessness 73

string data type 115

string property 64, 88, 94

success feedback

avoiding breaking changes in 223–225

interactions 128–129

suffixes 114

summary property, OpenAPI Specification 88, 90

Sunset header 332

Swagger Editor 82

Swagger UI 83

Swagger Viewer extension 82

T

tags property, OpenAPI Specification 169

text/csv 149, 150, 160

text/event-stream media type 283–284

text/plain 240

time-to-live values 258, 271

TLS (Transport Layer Security) encryption 188

tokens 186

Transport Layer Security (TLS) encryption 188

U

UI (user interface) 4

uniform interfaces 74, 145, 148, 160

UNIX timestamp 116, 140, 168

usability and straightfowardness 111–136

consistency of design and 146–147

flows 129–136

aggregating goals 134–135

goal chain 131–132

preventing errors 132–134

stateless flows 135–136

interactions 118–129

error feedback 121–128

inputs 119–121

success feedback 128–129

representations 112–118

data types and formats 115–116

names 113–115

ready-to-use data 116–118

usage (Output) column, API goals canvas 32

user-friendly scope 197

user guide 323–327

dynamic documentation 327

overview of common behaviors and principles 327

security 326–327

use cases 324–326

user interface (UI) 4

users, designing for

designing for users 36

V

versioning APIs 229–239

choosing versioning representation 232–234

granularity 234–238

understanding impact of 238–239

vs. implementation versioning 230–233

virtual goals organization 172

vnd prefix, media type 233, 237, 267–268

W

web APIs 4–6

Web Concepts website 341

WebDAV server 288

webhook APIs 280

WebSocket APIs 285

WebSub 281

What’s column, API goals canvas 32

Who’s column, API goals canvas 32

X

x- properties, OpenAPI Specification 330, 332

Y

YAML (YAML Ain’t Markup Language) 80