Pular para conteúdo

Visão Geral da API

Objetivo

Esta seção documenta os endpoints REST públicos do AnatoQuizUp. Do ponto de vista do consumidor (Frontend), a API pública é o BFF — ele é o único endereço externo. Os contratos descritos aqui (caminho, payload, status, formato de erro) continuam válidos: o BFF preserva path e contrato; a implementação real fica no Backend (fga-eps-mds/2026-1-AnatoQuizUp-Backend).

A API usa versionamento no caminho. Todos os endpoints de negócio documentados aqui partem do prefixo /api/v1. Por isso, nas páginas específicas, os títulos omitem esse prefixo para reduzir repetição. Quando a documentação mostra POST /autenticacao/login, o caminho completo é POST /api/v1/autenticacao/login.

Endpoints GET /health (BFF) e /api/v1/ia/* ficam fora do padrão geral: o primeiro é o health check do próprio BFF; o segundo é reservado ao serviço de AI e atualmente responde 503 IA_INDISPONIVEL enquanto o serviço estiver vazio (placeholder).

Execução local

Localmente, sobem três processos: Backend, BFF e Frontend.

Backend (2026-1-AnatoQuizUp-Backend)

cp .env.example .env
# Preencher INTERNAL_TOKEN (mesmo valor do BFF)
npm run db:up
npm run prisma:generate
npm run prisma:migrate -- --name init
npm run prisma:seed
npm run dev

Backend disponível em http://localhost:3333. Aceita requisições apenas com header X-Internal-Token válido (rota GET /health é a exceção).

BFF (2026-1-AnatoQuizUp-BFF)

cp .env.example .env
# Preencher INTERNAL_TOKEN e JWT_SECRET_KEY (mesmos valores do Backend)
npm ci
npm run dev

BFF disponível em http://localhost:4000. É o endereço usado pelo Frontend.

Caminho público

http://localhost:4000/api/v1

Exemplo completo:

POST http://localhost:4000/api/v1/autenticacao/login

Autenticação

A API usa tokens JWT para controlar sessões autenticadas. JWT é um token assinado pelo backend que carrega informações mínimas do usuário, como identificador e papel. Como ele é assinado, a API consegue validar se o token foi emitido pelo próprio servidor e se ainda pode ser aceito.

O login é feito pelo endpoint POST /autenticacao/login. Quando as credenciais estão corretas, a API retorna dois tokens:

  • accessToken: usado nas requisições protegidas;
  • refreshToken: usado para renovar a sessão sem exigir novo login.

Endpoints protegidos exigem o accessToken no cabeçalho Authorization:

Authorization: Bearer <accessToken>

Quando o accessToken expira, o frontend deve chamar POST /autenticacao/atualizar-token com o refreshToken. Esse endpoint retorna um novo par de tokens e permite manter a sessão ativa de forma controlada.

O encerramento da sessão acontece em POST /autenticacao/sair, que revoga o refreshToken informado.

Contratos de resposta

Os endpoints da API usam contratos padronizados para sucesso, paginação e erro. Isso permite que o frontend trate respostas de forma previsível, sem precisar criar um formato diferente para cada tela.

Sucesso

Operações que retornam um recurso único usam o formato:

{
  "mensagem": "Mensagem de sucesso.",
  "dados": {}
}

O campo mensagem descreve o resultado da operação. O campo dados contém o recurso retornado pela API.

Paginação

Listagens paginadas usam o formato:

{
  "dados": [],
  "metadados": {
    "page": 1,
    "limit": 10,
    "total": 0,
    "totalPages": 0
  }
}

O campo dados contém os itens da página atual. O campo metadados informa a página, o limite utilizado, o total de registros encontrados e o total de páginas disponíveis.

Erro

Erros usam o formato:

{
  "erro": {
    "codigo": "ERRO_DE_VALIDACAO",
    "mensagem": "Mensagem do erro.",
    "detalhes": {}
  }
}

O campo codigo é o valor mais importante para tratamento programático no frontend. A lista completa de códigos e status HTTP está em Erros e Contratos.

Endpoints públicos

Endpoints públicos podem ser acessados sem accessToken.

Método Endpoint Documentação
GET /health Esta página
POST /autenticacao/login Autenticação
POST /autenticacao/atualizar-token Autenticação
POST /autenticacao/cadastro Alunos
POST /autenticacao/recuperar-senha Autenticação
POST /autenticacao/redefinir-senha Autenticação
GET /autenticacao/alunos/nickname-disponivel Alunos
GET /autenticacao/alunos/email-disponivel Alunos
GET /autenticacao/alunos/nacionalidades Alunos
GET /autenticacao/alunos/opcoes-academicas Alunos
GET /autenticacao/alunos/localidades/estados Localidades
GET /autenticacao/alunos/localidades/estados/:uf/cidades Localidades

Endpoints autenticados

Endpoints autenticados exigem Authorization: Bearer <accessToken>.

Método Endpoint Documentação
GET /autenticacao/usuario-atual Autenticação
POST /autenticacao/sair Autenticação
GET /admin/usuarios Administração
GET /admin/usuarios/:id Administração
PATCH /admin/usuarios/:id/status Administração
POST /exemplos Exemplos
GET /exemplos Exemplos
GET /exemplos/:id Exemplos

Histórico de Versão

Data Versão Descrição Autor(es)
04/05/2026 1.0 Criação da documentação dos endpoints da API Arthur Carneiro
05/05/2026 1.1 Atualização para refletir o BFF como porta de entrada pública e mencionar o placeholder /api/v1/ia/* (PRD: Migração para Arquitetura com BFF) Miguel Moreira