Skip to content

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:

http
GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01

Uma resposta moldada por uma data de compatibilidade indica-lhe qual:

http
X-Api-Version: 2026-01-01
Vary: X-Api-Version

Os 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.

DataAlteração
2026-09-03aspects 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-10Cada 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.

bash
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:

bash
curl "https://api.astroapi.cloud/api/org/api-version" \
  -H "X-Api-Key: your_api_key"
json
{
  "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:

  1. Leia o registo de alterações acima e verifique que alterações caem entre a sua data atual e a nova.
  2. Envie a nova data em X-Api-Version em alguns pedidos, ou no seu ambiente de staging, e verifique as respostas.
  3. 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:

json
{
  "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.

AstroAPI Documentation