# Self-Describing API

Record: `arch: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#arch-self-describing-api

## 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/arch/api-contract.md)
- [Metadata](https://banes-lab.com/records/lex/metadata.md)

## reinforces

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

## enables

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

## conflicts-with

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

## tensions-with

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

## tensions

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