---
title: "Unite API — política de versões e uso"
description: "Versionamento, depreciação, limites, cache e idempotência da API pública do site da Unite."
canonical: https://unitebr.com/api-policy.md
last_updated: 2026-10-19
---

# Unite API — política de versões e uso

## Versionamento

A versão principal fica na URL (`/api/v1`). A versão exata vai no header `API-Version` (hoje 1.0.0). Mudanças compatíveis (campos ou endpoints novos) entram na mesma versão; mudanças incompatíveis ganham um novo prefixo (`/api/v2`).

## Depreciação

Antes de remover uma versão, as respostas passam a levar os headers `Deprecation` (RFC 9745) e `Sunset` (RFC 8594), com pelo menos 90 dias de antecedência, e um `Link` com `rel="deprecation"` para esta página.

## Limites

300 requisições por minuto por cliente, declaradas em `RateLimit-Limit` e `RateLimit-Policy`. Em 429, respeite `Retry-After`.

## Cache

Toda resposta 200 leva `ETag`; envie `If-None-Match` para receber 304 quando nada mudou.

## Idempotência

Todas as operações são GET, HEAD ou OPTIONS: seguras e idempotentes. Não há operações de escrita, então não há `Idempotency-Key`. Outros métodos recebem 405.

## Paginação

Listas usam cursor opaco: siga `next_cursor` até `null`. Cursores valem para a mesma consulta e a mesma revisão do conteúdo; um cursor inválido recebe 400.