16 Facilitating API design decision-making

Designing web APIs requires a steady stream of choices—naming, identifiers, status codes, pagination, formats—each with potential impact on usability, security, efficiency, and interoperability. This chapter offers a practical playbook for making those choices confidently and consistently: decide at the right moment, right-size the scope, reuse trusted past decisions, draw on vetted external practices, back conclusions with clear reasoning and evidence, and communicate decisions out loud to validate and align stakeholders. The goal is to reduce churn, avoid repeated debates, and turn good decisions into durable, reusable guidance.

To find solid answers to recurring design questions, the chapter details how to research effectively across internal and external sources: existing guidelines, current APIs, framework defaults, generic and domain standards, other organizations’ guidelines, public APIs, and reputable publications. It emphasizes validating how common a solution is and whether it fits your context, while treating “famous company X does it” as insufficient justification. It also recommends recording significant choices with an Architectural Decision Record, capturing the problem, options, pros and cons, reasoning, sources, and consequences. ADRs both force rigor during decision-making and create a transparent, lasting decision log.

Because ADRs alone are cumbersome for day-to-day work, the chapter advocates turning them into user-friendly API design guidelines that accelerate design and improve consistency. Effective guidelines combine clear principles and rules with actionable recipes (for example, search and list patterns, errors, pagination, filtering, and sorting), supported by examples, OpenAPI templates and shared components, and linting tools; they can also include design-process aids and selected implementation considerations. Guidelines should be built iteratively: start small with common operations, consider existing APIs thoughtfully, expand only when real needs emerge, include only rules that deliver tangible value, and evolve carefully to avoid unnecessary breaking changes. Framed this way, governance becomes an enabler—helping teams ship coherent, high-quality APIs at scale.

Designing APIs also involves thinking about simplifying our work to be confident and consistent seamlessly.

This example of ADR uses the MADR template. It’s a Markdown file, but you can use any support (wiki, for example). It describes the problem, solution, reasoning, and sources of information.

Basic guidelines cover the typical operations (create, search, read, update, and delete) and the principles and rules they rely on (covering HTTP usage, data, errors, and additional features).

FAQ