ADR-0008: Contrato de API — REST

Status

Accepted

Context and Problem Statement

O atenvi-bff precisa de um padrão de comunicação com os frontends (atenvi-admin, atenvi-web) que seja previsível, documentável e alinhado com o ecossistema NestJS.

Decision Drivers

• Simplicidade de consumo nos frontends
• Documentação automática via Swagger/OpenAPI (NestJS)
• Cacheable via HTTP
• Familiaridade da equipe

Considered Options

• REST
• GraphQL
• tRPC

Decision Outcome

Chosen option: REST, porque é suportado nativamente pelo NestJS com geração automática de documentação OpenAPI via decorators, e alinha com TanStack Query no frontend para cache e invalidação por endpoint.

Positive Consequences

• Swagger UI gerado automaticamente
• Cache HTTP nativo (GET requests)
• TanStack Query gerencia cache/invalidação por query key (URL)
• Sem overhead de schema GraphQL

Negative Consequences

• Over/under-fetching em telas com dados compostos
• Múltiplas requests para dados relacionados (mitigado pelo BFF agregando)

More Information

• Documentação: Swagger via @nestjs/swagger
• Padrão de versionamento: /api/v1/...
• Projetos: atenvi-bff (producer), atenvi-admin + atenvi-web (consumers)