🔌 API

O Bounded Context de API é a membrana de comunicação externa do nó PAEBIRU. Ele expõe as capacidades do sistema para o mundo exterior através de interfaces REST e gRPC, garantindo observabilidade e auditabilidade através de Recibos Soberanos.

1. Recibos Soberanos (DRE)

A principal saída da API não são apenas dados, mas Recibos Soberanos gerados pelo Distributed Receipt Engine (DRE):

Verificabilidade: Cada resposta da API é acompanhada por uma assinatura criptográfica pós-quântica (ML-DSA).
Prova de Execução: O recibo serve como prova de que uma computação ou transação ocorreu em um determinado nó sob certas condições.
Monetização: Recibos podem ser usados para liquidação no BC de Economia.

2. Interface HTTP (Axum)

A implementação padrão utiliza o framework Axum para oferecer uma interface de alto desempenho:

Endpoints de Saúde: /healthz e /readiness para orquestração.
Métricas: /metrics no formato Prometheus para monitoramento de metabolismo.
Comandos: Endpoints para injeção de plasmídeos e consulta de estado causal.

3. Observabilidade e Tracing

O PAEBIRU segue o padrão OpenTelemetry (OTel) para garantir que cada mensagem possa ser rastreada através da malha:

Distributed Tracing: Uso de tracing e opentelemetry para correlacionar eventos entre nós.
Logs Estruturados: Logs em formato JSON para fácil ingestão por sistemas como Grafana Loki.
Sensores de Stress: A API expõe o estado dos sensores algedônicos para sistemas de monitoramento externos.

4. Invariantes do Domínio

Segurança por Default: Nenhum endpoint de mutação de estado é exposto sem autenticação mútua (mTLS) ou prova de identidade soberana.
Backpressure de API: Se o nó estiver saturado (metabolismo alto), a API retorna 429 Too Many Requests com base nos tokens do Kernel.
Idempotência: Operações de mutação devem ser idempotentes através de identificadores únicos no cabeçalho da API.

5. Veja também