Self-Describing API

Kind: principle

Layer: Declarative Core

Record: architecture:self-describing-api

Severity: recommended

Scope: API, integration

Canonical: Ontology

A design rule that an API publishes machine-readable descriptions of its operations, payloads and errors.

Listed in Architecture principles, after Self-Describing Architecture and before Self-Describing Structures.

Requires

• API Contract
• Metadata

Reinforces

• Discoverability
• Interoperability

Enables

• Client Generation
• HATEOAS-style Navigation

Conflicts with

• Opaque API

In tension with

• Payload Verbosity

Tensions

• Self-Describing API / Payload Verbosity

Violated by

• Opaque API

Refactored by

• Define Contract
• Declare Capability
• Standard Error Contract

Severity

• recommended

Category

• Metadata / Self-Description / Declarative Systems

Enforced by

• runtime/entrypoints/validation.entrypoint.ts

Linked from

• Contracts / Interfaces / Compatibility
• Contracts / Interfaces / Compatibility
• Core Vocabulary
• Metadata / Self-Description / Declarative Systems
• Quality Attributes
• Severity levels
• The resolutions