# Self-Describing API

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

Record: `architecture:self-describing-api`
Kind: principle
Layer: [Declarative Core](https://banes-lab.com/records/layer/declarative-core.md)
Severity: recommended
Scope: API, integration
Canonical: https://banes-lab.com/ontology#architecture-self-describing-api

Listed in [Architecture principles](https://banes-lab.com/api/records/architecture.md), after [Self-Describing Architecture](https://banes-lab.com/records/architecture/self-describing-architecture.md) and before [Self-Describing Structures](https://banes-lab.com/records/architecture/self-describing-structures.md).

## Repair

- Refactored by: Add OpenAPI, Add Metadata, Normalize Responses
- Detected by: missing OpenAPI/metadata
- Violated by: undocumented endpoints, opaque error responses
- Measured by: API documentation/contract coverage
- Enforced by: API linting, docs gates

## Requires

- [API Contract](https://banes-lab.com/records/architecture/api-contract.md)
- [Metadata](https://banes-lab.com/records/lexicon/metadata.md)

## Reinforces

- [Discoverability](https://banes-lab.com/records/lexicon/discoverability.md)
- [Interoperability](https://banes-lab.com/records/architecture/interoperability.md)

## Enables

- [Client Generation](https://banes-lab.com/records/lexicon/client-generation.md)
- [HATEOAS-style Navigation](https://banes-lab.com/records/lexicon/hateoas-style-navigation.md)

## Conflicts with

- [Opaque API](https://banes-lab.com/records/lexicon/opaque-api.md)

## In tension with

- [Payload Verbosity](https://banes-lab.com/records/lexicon/payload-verbosity.md)

## Tensions

- [Self-Describing API / Payload Verbosity](https://banes-lab.com/records/tension/payload-verbosity-self-describing-api.md)

## Severity

- [recommended](https://banes-lab.com/records/vocabulary/severity-recommended.md)

## Category

- [Metadata / Self-Description / Declarative Systems](https://banes-lab.com/records/architecture-category/metadata-self-description-declarative-systems.md)

## Linked from

- [Contracts / Interfaces / Compatibility](https://banes-lab.com/ontology/principles/architecture-category-contracts-interfaces-compatibility.md)
- [Core Vocabulary](https://banes-lab.com/ontology/lexicon/lexicon-category-core-vocabulary.md)
- [Metadata / Self-Description / Declarative Systems](https://banes-lab.com/ontology/lexicon/lexicon-category-metadata-self-description-declarative-systems.md)
- [Quality Attributes](https://banes-lab.com/ontology/lexicon/lexicon-category-quality-attributes.md)
- [Severity levels](https://banes-lab.com/ontology/schema/the-vocabulary-severity.md)
- [The resolutions](https://banes-lab.com/ontology/schema/the-resolutions.md)