RESTful APIs

Esta especificação consolida as diretrizes para construção, consumo e documentação de APIs RESTful na plataforma Guardia. Seu objetivo é garantir padronização nas respostas e comportamentos, promovendo interoperabilidade, rastreabilidade e clareza para consumidores internos e externos.

As APIs REST da Guardia seguem os padrões definidos pelas RFCs oficiais do protocolo HTTP, com ajustes necessários para resolução de possíveis ambiguidades e aderência aos princípios de Compliance by Design.

A especificação RESTful está estruturada em módulos reutilizáveis e versionáveis, que cobrem os seguintes aspectos:

Tema	Descrição
Status Codes	Lista dos status HTTP permitidos e regras de uso.
Payloads de Resposta	Formato unificado de respostas para sucesso e erro.
Paginação	Estrutura padrão para navegação entre recursos paginados.
Ordenação	Regras para uso de parâmetros order_by e sort.
Headers	Headers padrão e customizados utilizados nas APIs.

IMPORTANTE: Todas as regras aqui descritas DEVEM ser aplicadas a qualquer endpoint HTTP implementado na plataforma, salvo exceções justificadas e documentadas em ADR.