Metodologia da API

Cada conversão que o Convertitive disponibiliza também é um endpoint JSON em /api/v1/. A API existe desde o FAZ 4 e serve os mesmos fatores e fórmulas que a interface — se um resultado está correto na página, ele está correto na API.

Design de endpoints

Estilo REST. O caminho descreve o recurso, a query string carrega os parâmetros. Exemplos:

• GET /api/v1/convert/unit?category=length&from=cm&to=inches&value=5
• GET /api/v1/convert/currency?from=USD&to=EUR&value=100
• GET /api/v1/convert/color?from=hex&to=rgb&value=%23FF6B35
• GET /api/v1/categories — lista todas as categorias de unidades
• GET /api/v1/health/ — saúde do serviço (tempo ativo + versão)

Sem corpos POST. Todas as entradas são parâmetros de query. Idempotente, cacheável, amigável para navegadores.

Envelope de resposta

Cada resposta bem-sucedida usa o mesmo formato:

{
  "ok": true,
  "data": { /* específico do endpoint */ },
  "meta": { /* metadados opcionais: rateDate, factor, etc. */ }
}

Cada resposta de erro:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAM",
    "message": "Explicação legível por humanos",
    "param": "from"
  }
}

Códigos de status HTTP padrão: 200 para sucesso, 400 para erros de entrada, 404 para categorias/unidades desconhecidas, 500 apenas quando algo realmente quebrou. Não trate 4xx como tentável novamente.

Política de CORS

Access-Control-Allow-Origin: * em cada endpoint de API. Use de qualquer origem, incluindo desenvolvimento local. Nenhuma preflight necessária porque toda solicitação é GET sem cabeçalhos personalizados — as regras de solicitação simples se aplicam.

Sem autenticação

Sem chave de API, sem OAuth, sem solicitações assinadas. Cada endpoint é anônimo. Três razões:

1. Os dados não são valiosos o suficiente para restringir. Fatores de conversão de unidades são de domínio público. As taxas do ECB são republicadas publicamente por ~20 serviços. Cobrar por eles seria cobrar pelos dados de outra pessoa.
2. A autenticação adiciona atrito para o caso de uso dominante. Um desenvolvedor testando uma funcionalidade, um estudante fazendo script de uma comparação para dever de casa, um entusiasta construindo um rastreador — nenhum deles quer se registrar primeiro.
3. Limites de taxa lidam com abuso. Os padrões do Cloudflare e o custo computacional trivial de cada conversão significam que alguém tentando fazer scraping do Convertitive pode obter os dados mais rápido espelhando diretamente o feed público do ECB.

Versionamento

O prefixo /api/v1/ é intencional. Quando o envelope de resposta ou o formato de erro muda de forma significativa, um /api/v2/ é lançado em paralelo; v1 é suportado por pelo menos 12 meses após o lançamento da v2.

Correções de bugs e mudanças aditivas (novos endpoints, novos campos opcionais nas respostas) são lançadas continuamente sem incremento de versão.

Frescor das taxas de câmbio

Os endpoints de câmbio retornam a taxa de mercado médio do ECB armazenada em cache por uma hora via ISR. O campometa.rateDate em cada resposta de câmbio informa quando a taxa foi publicada (sempre um dia útil recente do ECB). Para trabalho em tempo real de alta precisão, obtenha as taxas do seu corretor; para todo o resto, nosso cache é adequado.

Detalhes do algoritmo: ciclo de vida da solicitação, do início ao fim

Cada solicitação de API passa pelo mesmo pipeline de seis estágios para que o comportamento observável seja uniforme em todos os endpoints:

1. Roteamento de borda. O Cloudflare corresponde a solicitação ao mapa de rotas em cache e serve a resposta em cache ou encaminha para a função Next.js. Latência p50 de cache hit: ~25 ms; p50 de cache miss: ~70 ms.
2. Método e preflight CORS. Rejeita métodos não GET com 405. Aplica o cabeçalho Access-Control-Allow-Origin: * em cada resposta.
3. Validação de esquema. Analisa parâmetros de query com um esquema no estilo Zod. Parâmetros ausentes ou malformados retornam 400 com { ok: false, error: { code: "INVALID_PARAM", param } }.
4. Resolve a conversão. Procura a conversão de destino no mesmo registro que a interface usa.
5. Formata o envelope. Sempre { ok: true, data, meta }. Números são serializados como números JSON (não strings) por RFC 8259.
6. Cabeçalhos de cache. Respostas de câmbio recebem Cache-Control: public, max-age=3600, stale-while-revalidate=86400; respostas de unidade/cor recebem max-age=31536000, immutable porque a matemática nunca muda.

Pressupostos e limitações

• Apenas GET. Sem POST/PUT/DELETE.
• Sem análise de corpo de solicitação. Todas as entradas são parâmetros de query com codificação de URL. Entradas maiores que ~2 KB podem atingir limites de comprimento de URL em intermediários.
• Limites de taxa são de borda de rede, não por chave de API. Clientes de alto volume compartilhando um NAT podem compartilhar a mesma cota; espelhe os dados relevantes localmente para cargas de produção.
• Sem SLA. A API é de melhor esforço. Faça cache agressivamente e trate 5xx como transiente.
• Apenas JSON, sem XML / msgpack.

Documentação ao vivo em /api/.