Diretrizes de Versionamento, Depreciação e Rate Limiting

Esta página descreve as regras de ciclo de vida e controle de fluxo das APIs e integrações para Agentes de IA da Pipocando Festas e Eventos.

1. Versionamento REST (URL Path)

Todas as rotas REST públicas utilizam versionamento explícito no caminho da URL: https://pipocando.org/api/v1/.

Mudanças compatíveis (como novos campos opcionais em respostas JSON ou novas ferramentas no MCP) são introduzidas sem quebra de versão. Alterações que quebrem retrocompatibilidade serão lançadas em uma nova versão de rota (ex: /api/v2/).

2. Política de Depreciação e Cabeçalho Sunset (RFC 8594)

Garantimos um período mínimo de transição de 24 meses antes do desligamento definitivo de qualquer endpoint depreciado.

Endpoints depreciados anunciam seu cronograma de término emitindo os cabeçalhos padrão HTTP:

Deprecation: @2031-12-31
Sunset: Wed, 31 Dec 2031 23:59:59 GMT
Link: <https://pipocando.org/docs/versioning>; rel="deprecation"

3. Rate Limiting e Cabeçalhos RFC

Para garantir estabilidade, segurança e evitar abusos em agentes automatizados, os seguintes cabeçalhos de controle de fluxo acompanham cada resposta da API:

RateLimit-Limit: 120 — Número máximo de requisições permitidas por janela.
RateLimit-Remaining: 119 — Requisições restantes na janela atual.
RateLimit-Reset: 60 — Segundos restantes até a reinicialização da janela.
RateLimit-Policy: 120;w=60 — Política formal de 120 requisições a cada 60 segundos.

Caso o limite seja excedido, a resposta retornará status HTTP 429 Too Many Requests com o cabeçalho Retry-After: 60 e payload de erro JSON estruturado.

4. Model Context Protocol (MCP)

O servidor MCP disponível em https://pipocando.org/api/mcp segue a especificação MCP 2024-11-05 via Streamable HTTP, compartilhando a mesma política de estabilidade.