Architecture decision record

As explained in The Design of Web APIs, Second Edition

An architectural decision record is a documented record of a significant software or API design decision, including its rationale, alternatives, and consequences.

An architectural decision record (ADR) captures a significant API or software design choice, its rationale, alternatives, sources, and consequences. It preserves decisions and forces their justification. section 16.2.3

A practical ADR typically records:

• The context and problem statement. section 16.2.3
• The options considered, with their advantages and disadvantages. section 16.2.3
• The decision, reasoning, consequences, and supporting information sources. section 16.2.3

Choosing resource ID property names

An API design ADR can compare resource ID naming options, explain the selected convention, and record both beneficial and adverse consequences. The decision log can later support API design guidelines. section 16.2.3 section 16.5.4

Figure 16.2 This example of ADR uses the MADR template. It’s a Markdown file, but you can also use a wiki page or any other format. It describes the problem, solution, reasoning, and sources of information.

Use the MADR-style artifact as a compact visual model: problem, solution, reasoning, and information sources in Markdown or a wiki page. section 16.2.3

How The Design of Web APIs, Second Edition covers it

How deep it goes

Explains context, alternatives, pros and cons, reasoning, consequences, and sources, but remains a concise format overview.

Examples

Uses resource ID property naming, MADR Markdown files, wiki pages, and decision-log entries as concrete artifacts.

What it assumes

Assumes an API design problem requiring alternatives and rationale, while supplying the ADR structure for organizing that reasoning.

What you can do after

Build justified API decisions that can inform consistent, efficient, secure, and interoperable design guidelines.

How it connects

Connects API design decisions with API design guidelines, API governance, and OpenAPI templates or shared components.

liveBookmanning.com

Read The Design of Web APIs, Second Edition on liveBook Get the book at manning.com

Also explained in

• 

  liveBookmanning.com
  Authorization in ActionAn architectural decision record is a version-controlled document that captures the context, rationale, decision, consequences, and related artifacts for an architectural choice.
• 

  liveBookmanning.com
  Collaborative Software Design: How to facilitate domain modeling decisionsA structured document that records an architectural decision, its context, and its consequences.

Compare how 3 books explain architecture decision record →

Related concepts

• architectural decisionuses · An architectural decision is a choice about the significant structure, behavior, interactions, or technical constraints of a software system.
• design documentcontrasts with · A design document is written material describing an intended software design, including its structure, technical decisions, rationale, constraints, or implementation considerations.
• artificial intelligenceused by · Artificial intelligence is the field concerned with creating computational systems that perform tasks associated with human intelligence, such as learning, reasoning, perception, or decision-making.

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.