Bloco Endpoints

Sintaxe básica

O bloco Endpoints descreve as operações da API. Cada operação é declarada com a keyword endpoint seguida de um nome descritivo em PascalCase:

Endpoints {
  endpoint ListarProdutos {
    rota: GET /produtos
    autenticacao: nao-requerida

    Respostas {
      200: Lista de produtos ativos
    }
  }
}

O campo rota combina o método HTTP com o caminho: GET, POST, PUT, PATCH, DELETE. O campo autenticacao aceita obrigatoria ou nao-requerida.

Entrada e Params

O sub-bloco Entrada declara os campos do body da requisição. O sub-bloco Params declara os parâmetros de query string. Ambos usam a mesma sintaxe de campos do bloco Dados:

endpoint AgendarConsulta {
  rota: POST /consultas
  autenticacao: obrigatoria
  regras: HorarioDisponivel, PacienteAtivo

  Entrada {
    medico_id: inteiro, obrigatorio
    paciente_id: inteiro, obrigatorio
    data_hora: data-hora, obrigatorio
    observacoes: texto(500), opcional
  }

  Respostas {
    201: Consulta agendada com sucesso — retorna objeto da consulta
    400: Horário indisponível para este médico
    404: Médico ou paciente não encontrado
    422: Data deve ser futura
  }
}

Endpoint com query string

endpoint ListarConsultas {
  rota: GET /consultas
  autenticacao: obrigatoria

  Params {
    medico_id: inteiro, opcional
    status: texto(30), opcional
    data_inicio: data, opcional
    data_fim: data, opcional
    skip: inteiro, opcional, padrao: 0
    take: inteiro, opcional, padrao: 20
  }

  Respostas {
    200: Lista paginada de consultas com total
  }
}

Sub-bloco Respostas

O sub-bloco Respostas declara os códigos HTTP possíveis e uma descrição do que cada um significa no contexto do endpoint. A IA usa essas informações para implementar os retornos corretos:

Respostas {
  200: Operação realizada com sucesso
  201: Recurso criado — retorna o objeto com ID gerado
  204: Operação realizada — sem corpo na resposta
  400: Dados inválidos — detalhe no campo message
  401: Não autenticado
  403: Sem permissão para esta operação
  404: Recurso não encontrado
  409: Conflito — recurso já existe
  422: Regra de negócio violada
  429: Muitas requisições — aguardar antes de tentar novamente
}

Regras aplicadas

O campo regras vincula regras do bloco Regras ao endpoint. A IA sabe que precisa verificar essas condições antes de processar a operação. Múltiplas regras são separadas por vírgula:

endpoint ExcluirConta {
  rota: DELETE /conta
  autenticacao: obrigatoria
  regras: ConfirmarSenha, SemPedidosPendentes, RegistrarAuditoria

  Entrada {
    senha_confirmacao: texto(200), obrigatorio
    motivo: texto(500), opcional
  }

  Respostas {
    204: Conta excluída com sucesso
    400: Senha incorreta
    409: Conta tem pedidos pendentes que impedem a exclusão
  }
}

Rotas parametrizadas

Parâmetros de rota (segmentos dinâmicos na URL) são declarados com a convenção padrão de dois pontos. A IA interpreta :id e :slug como parâmetros de path:

endpoint BuscarProduto {
  rota: GET /produtos/:id
  autenticacao: nao-requerida

  Respostas {
    200: Dados completos do produto incluindo variantes
    404: Produto não encontrado ou inativo
  }
}

endpoint AtualizarProduto {
  rota: PATCH /produtos/:id
  autenticacao: obrigatoria
  regras: ApenasAdmin

  Entrada {
    nome: texto(200), opcional
    preco: decimal, opcional
    ativo: booleano, opcional
  }

  Respostas {
    200: Produto atualizado — retorna objeto completo
    403: Sem permissão de administrador
    404: Produto não encontrado
  }
}

Instruções livres em endpoints

Quando o comportamento de um endpoint tem nuances que não cabem nos campos estruturados, use instruções livres com hífen ou notas de arquiteto:

endpoint ProcessarPagamento {
  rota: POST /pagamentos
  autenticacao: obrigatoria
  regras: SaldoSuficiente, LimiteTransacao
  /// Integração com Stripe — usar idempotency key para evitar cobranças duplas

  - Salvar intenção de pagamento antes de chamar a API do gateway
  - Em caso de falha no gateway, retornar 502 (não 500)
  - Disparar evento de pagamento para o serviço de notificações após sucesso

  Entrada {
    valor: decimal, obrigatorio
    moeda: texto(3), obrigatorio, padrao: BRL
    metodo: texto(30), obrigatorio
  }

  Respostas {
    201: Pagamento processado — retorna ID da transação
    402: Pagamento recusado pelo gateway
    422: Saldo insuficiente ou limite excedido
    502: Falha temporária no gateway de pagamento
  }
}