An API design guideline is a documented, user-friendly recommendation for making consistent and effective API design decisions. It records trusted choices, explains how to apply them, and helps produce user-friendly, secure, efficient, interoperable, and maintainable APIs. Guidelines support individuals as well as teams and can stand alone without API governance. section 16.0 section 16.3
A useful guideline combines principles and rules with actionable recipes. Rules establish decisions such as plural resource names, permitted HTTP methods, pagination defaults, error formats, or domain-specific identifiers. Recipes group those rules around tasks and explain purpose, parameters, paths, responses, errors, limitations, and contextual variations. section 16.4.1 section 16.4.2
Guidelines can include the following working artifacts and decision aids:
- Principles and rules backed by ADRs, with MUST, SHOULD, and MAY expressing requirement levels. section 16.4 section 16.4.1
- OpenAPI templates, shared libraries, examples, and authoring conventions that make recurring designs consistent. section 16.4 section 17.7
- Linting rules that automate valid recommendations, identify design or authoring problems, and link findings to their guideline rationale. section 18.1.2 section 18.4.1
A search-operation recipe
A recipe for searching or listing collection elements can define the operation’s purpose, resource path, filter, pagination, and sorting parameters, success and error responses, no-result behavior, headers, and sensitive-filter exceptions. It removes repeated debates about response conventions so designers can concentrate on whether the returned model serves consumers. section 16.3.1 section 16.4.2
Build guidelines incrementally: start with typical create, read, search, update, and delete operations; use existing APIs and researched standards as evidence; expand when real questions arise; retain only rules that add value; and modify them carefully to avoid breaking existing APIs. New APIs can adopt a standardized look and feel while existing APIs evolve selectively. section 16.5 section 16.5.1 section 16.5.2 section 16.5.5
Figure 16.3 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).
Use the figure to see how basic operation recipes depend on shared principles and rules covering HTTP, data, errors, and additional features. section 16.5.1
