Versionamento da API
A AstroAPI versiona alterações incompatíveis com uma data de compatibilidade em vez de um número de versão no URL. Os caminhos dos endpoints nunca mudam; fixa uma data e continua a receber exatamente o comportamento que vigorava nessa data.
A sua versão
Envie a data de compatibilidade contra a qual desenvolveu no cabeçalho X-Api-Version:
GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01Uma resposta moldada por uma data de compatibilidade indica-lhe qual:
X-Api-Version: 2026-01-01
Vary: X-Api-VersionOs endpoints cuja saída não depende da versão omitem ambos os cabeçalhos. GET /api/modules devolve o mesmo corpo em qualquer data, portanto não há nada a reportar nem nada que uma cache tenha de manter separado. Envie um X-Api-Version explícito e é-lhe devolvido em qualquer endpoint, para que possa sempre confirmar que um valor foi aceite.
Para ler a versão a que a sua organização se resolve, use GET /api/org/api-version; o seu effectiveApiVersion é a data que se aplica quando um pedido não traz cabeçalho próprio.
Se não enviar cabeçalho, os pedidos usam a versão fixada da sua organização e, se não tiver fixado nenhuma, a linha de base 2026-01-01. O novo comportamento nunca lhe é aplicado automaticamente — uma integração escrita hoje continua a funcionar inalterada, independentemente do que lançarmos depois.
Registo de alterações
Cada alteração incompatível está listada aqui com a data em que entra em vigor. Fixar uma data dá-lhe todas as alterações nessa data ou anteriores.
| Data | Alteração |
|---|---|
2026-09-03 | aspects em POST /api/calc/transit está agrupado: uma entrada por planeta em trânsito, aspeto e planeta natal, com o texto de interpretação uma só vez e cada passagem do período em occurrences. Antes havia uma entrada por passagem, repetindo o texto. Ver Trânsitos. |
2026-09-10 | Cada ponto de POST /api/calc/natal traz declination (graus, norte positivo) e outOfBounds (além da declinação máxima do Sol para essa data). Antes nenhum dos dois campos estava presente. Ver Declinações. |
A linha de base 2026-01-01 é a versão mais antiga que servimos. Fixar uma data anterior é aceite e resolve-se para a linha de base.
Fixar a sua organização
Em vez de acrescentar um cabeçalho a cada chamada, fixe a sua organização uma vez. Todos os pedidos sem versão passarão então a usar essa data.
curl -X PATCH "https://api.astroapi.cloud/api/org/api-version" \
-H "Content-Type: application/json" \
-H "X-Api-Key: your_api_key" \
-d '{
"data": {
"type": "organizations",
"attributes": { "apiVersion": "2026-01-01" }
}
}'Leia a fixação atual, juntamente com o intervalo por que pode optar:
curl "https://api.astroapi.cloud/api/org/api-version" \
-H "X-Api-Key: your_api_key"{
"data": {
"type": "organizations",
"id": "org_123",
"attributes": {
"apiVersion": "2026-01-01",
"effectiveApiVersion": "2026-01-01",
"baselineApiVersion": "2026-01-01",
"latestApiVersion": "2026-01-01"
}
}
}Envie "apiVersion": null para limpar a fixação e voltar à linha de base.
Atualizar em segurança
O cabeçalho ganha sempre à fixação da organização, o que torna possível um lançamento seguro:
- Leia o registo de alterações acima e verifique que alterações caem entre a sua data atual e a nova.
- Envie a nova data em
X-Api-Versionem alguns pedidos, ou no seu ambiente de staging, e verifique as respostas. - Quando estiver satisfeito, fixe a sua organização na nova data e volte a omitir o cabeçalho.
Como o cabeçalho substitui a fixação por pedido, também pode fazer o inverso: fixar a sua organização em frente e enviar temporariamente uma data mais antiga a partir de um serviço que ainda não migrou.
Clientes de navegador e incorporações
Os contextos que não conseguem definir cabeçalhos de pedido — incorporações <img>, <iframe> e <script>, URLs de mapa assinados — aceitam a data como parâmetro de consulta:
https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...O cabeçalho tem precedência quando ambos estão presentes. Para fetch() e XHR, use o cabeçalho; X-Api-Version é permitido por CORS e exposto nas respostas, para que possa ler que versão foi aplicada.
Validação
Um valor malformado devolve 400 Bad Request em vez de recuar em silêncio:
{
"error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}O valor tem de ser uma data de calendário real no formato YYYY-MM-DD. Uma data bem formada fora do intervalo suportado é limitada em vez de rejeitada: anterior à linha de base resolve-se para a linha de base; posterior à alteração mais recente resolve-se para o comportamento mais recente.
Cache
As respostas cujo corpo pode diferir por versão são marcadas com Vary: X-Api-Version, para que uma cache partilhada ou um CDN à frente da sua integração mantenha essas versões separadas. As respostas iguais em qualquer data não trazem Vary, o que permite a uma cache servir uma única entrada para todos os seus clientes em vez de uma por data. Se você próprio guardar respostas da API em cache, inclua a data de compatibilidade na chave de cache para os endpoints que trazem o cabeçalho.
O que conta como alteração incompatível
Alterações que recebem uma data e aparecem no registo:
- Remover ou renomear um campo numa resposta
- Alterar o tipo ou a forma de um campo existente
- Tornar obrigatório um campo opcional, ou sempre presente um campo omitido
- Alterar o significado de um valor existente
- Remover um endpoint ou alterar a sua semântica
Alterações que saem sem versão, porque não podem quebrar um cliente correto:
- Acrescentar um novo endpoint
- Acrescentar um novo parâmetro de pedido opcional
- Acrescentar um novo campo a uma resposta
- Acrescentar um novo valor a um enum que apenas lê
- Correções que alinham o comportamento com a documentação
Escreva a sua integração de modo a ignorar campos de resposta desconhecidos. As alterações aditivas chegam a todas as versões, incluindo a sua.