Guideline
A guideline is a recommendation or principle that directs how an activity is performed or decisions are made, without necessarily imposing an absolute requirement.
The Design of Web APIs, Second Edition
An API design guideline is a documented recommendation for making consistent and effective API design decisions.
- How it is used
- Guides recurring API design decisions and standardizes solutions across individual, team, and organizational work.
- How deep it goes
- Extends from principles and rules to detailed recipes, OpenAPI artifacts, and automated checks, while deferring exhaustive edge cases until needed.
- Examples
- Uses search-operation recipes, pagination, filtering, error handling, resource naming, HTTP statuses, OpenAPI libraries, and linting rules as concrete applications.
- What you can do after
- Build it from scratch by creating focused rules and recipes, applying them to API designs, and automating suitable checks with a linter.
Read how The Design of Web APIs, Second Edition explains guideline →
"Looks Good to Me"
A guideline is a recommended rule or principle that directs how code reviews should be conducted and how unclear situations should be handled.
- How it is used
- Directs code review behavior, resolves ambiguity, and establishes a shared path for consistent, maintainable, and effective reviews.
- How deep it goes
- Defines purpose, documentation, adaptation, participation, and conduct, while deferring detailed policy contents to team decisions.
- Examples
- Uses open editable documents, respectful-comment rules, explicit consequences, and collaboratively defined review practices as concrete artifacts.
- What you can do after
- Apply it via a shared, revisable set of code review rules that supports decisions and makes interpersonal expectations actionable.
Related concepts
- style guidecontrasts with · A style guide is a documented set of conventions for consistently formatting, naming, organizing, or presenting source code.
- api governanceused by · API governance is the organizational practice of establishing, coordinating, and enforcing policies, standards, and controls for API development, management, and security.
- contractused by · An API contract is a specification of the operations, data, and behavioral expectations that govern interactions between software components.
- architecture decision recordcontrasts with · An architecture decision record is a document that captures an architectural decision, its context, rationale, and consequences.
- WCAGincludes · WCAG is a W3C standard providing testable recommendations and success criteria for making web content accessible to people with disabilities.
- linter ruleused by · A linter rule is a configurable condition applied by a linter to detect or enforce specified patterns or constraints in code or other artifacts.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.