Uniform Interface

Kind: constraint

Layer: Contracts Core

Record: architecture:uniform-interface

Severity: recommended

Scope: API, resource boundary

Canonical: Ontology

A rule or precondition that every resource in an API uses the same verbs, response shapes and error format.

Listed in Architecture principles, after Interoperability and before Consumer-Driven Contracts.

Requires

• Consistent Semantics
• Stable Contracts

Reinforces

• Principle of Least Surprise

Enables

• API Usability

Conflicts with

• Ad-Hoc Endpoints
• Chatty Interface

In tension with

• Specialized Endpoints

Tensions

• Uniform Interface / Specialized Endpoints

Violated by

• Ambiguous API
• Inconsistent Error Model

Refactored by

• Standardize the Interface
• Standard Error Contract

Severity

• recommended

Category

• Contracts / Interfaces / Compatibility

Reinforced by

• Composite Pattern

Linked from

• Anti-patterns
• Structural Patterns
• Schema / Canonical Data / Semantics
• Contracts / Interfaces / Compatibility
• Core Vocabulary
• Schema / Canonical Data / Semantics
• Severity levels
• The resolutions