Skip to content

Versionnage de l'API ​

AstroAPI versionne les changements incompatibles au moyen d'une date de compatibilité plutôt que d'un numéro de version dans l'URL. Les chemins des points de terminaison ne changent jamais ; vous épinglez une date et continuez de recevoir exactement le comportement en vigueur à cette date.

Votre version ​

Envoyez la date de compatibilité sur laquelle vous avez développé dans l'en-tête 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

Une réponse façonnée par une date de compatibilité vous indique laquelle :

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

Les points de terminaison dont la sortie ne dépend pas de la version omettent les deux en-têtes. GET /api/modules renvoie le même corps à toute date : il n'y a donc rien à signaler et rien qu'un cache doive séparer. Envoyez un X-Api-Version explicite et il vous est renvoyé sur n'importe quel point de terminaison, ce qui vous permet de toujours confirmer qu'une valeur a été acceptée.

Pour relire la version à laquelle votre organisation se résout, utilisez GET /api/org/api-version ; son effectiveApiVersion est la date qui s'applique lorsqu'une requête ne porte pas d'en-tête propre.

Si vous n'envoyez aucun en-tête, les requêtes utilisent la version épinglée de votre organisation et, si vous n'en avez épinglé aucune, la ligne de base 2026-01-01. Un nouveau comportement ne vous est jamais appliqué automatiquement — une intégration écrite aujourd'hui continue de fonctionner inchangée, quoi que nous publiions par la suite.

Journal des modifications ​

Chaque changement incompatible est répertorié ici avec la date de son entrée en vigueur. Épingler une date vous donne tous les changements à cette date ou avant.

DateChangement
2026-09-03aspects sur POST /api/calc/transit est regroupé : une entrée par planète en transit, aspect et planète natale, avec le texte d'interprétation une seule fois et chaque passage de la période sous occurrences. Auparavant une entrée par passage, chacune répétant le texte. Voir Transits.
2026-09-10Chaque point de POST /api/calc/natal porte declination (degrés, nord positif) et outOfBounds (au-delà de la déclinaison maximale du Soleil pour cette date). Auparavant aucun des deux champs n'était présent. Voir Déclinaisons.

La ligne de base 2026-01-01 est la plus ancienne version que nous servons. Épingler une date antérieure est accepté et se résout à la ligne de base.

Épingler votre organisation ​

Plutôt que d'ajouter un en-tête à chaque appel, épinglez votre organisation une fois. Toutes les requêtes sans version utiliseront alors cette date.

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" }
    }
  }'

Relisez l'épinglage actuel, ainsi que la plage dans laquelle vous pouvez choisir :

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"
    }
  }
}

Envoyez "apiVersion": null pour effacer l'épinglage et revenir à la ligne de base.

Mettre à niveau en toute sécurité ​

L'en-tête l'emporte toujours sur l'épinglage de l'organisation, ce qui rend possible un déploiement sûr :

  1. Lisez le journal ci-dessus et vérifiez quels changements se situent entre votre date actuelle et la nouvelle.
  2. Envoyez la nouvelle date dans X-Api-Version sur quelques requêtes, ou dans votre environnement de préproduction, et vérifiez les réponses.
  3. Une fois satisfait, épinglez votre organisation à la nouvelle date et retirez de nouveau l'en-tête.

Comme l'en-tête écrase l'épinglage requête par requête, vous pouvez aussi faire l'inverse : épingler votre organisation en avant et envoyer temporairement une date plus ancienne depuis un service que vous n'avez pas encore migré.

Clients navigateur et intégrations ​

Les contextes qui ne peuvent pas définir d'en-têtes de requête — intégrations <img>, <iframe> et <script>, URLs de carte signées — acceptent la date sous forme de paramètre de requête :

https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...

L'en-tête a la priorité lorsque les deux sont présents. Pour fetch() et XHR, utilisez l'en-tête ; X-Api-Version est autorisé par CORS et exposé sur les réponses, ce qui vous permet de relire la version appliquée.

Validation ​

Une valeur mal formée renvoie 400 Bad Request plutôt que de retomber silencieusement sur autre chose :

json
{
  "error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}

La valeur doit être une véritable date calendaire au format YYYY-MM-DD. Une date bien formée hors de la plage prise en charge est bornée plutôt que rejetée : antérieure à la ligne de base, elle se résout à la ligne de base ; postérieure au changement le plus récent, elle se résout au comportement le plus récent.

Mise en cache ​

Les réponses dont le corps peut différer selon la version sont marquées Vary: X-Api-Version, afin qu'un cache partagé ou un CDN placé devant votre intégration garde ces versions séparées. Les réponses identiques à toute date ne portent pas de Vary, ce qui permet à un cache de servir une seule entrée pour tous vos appelants plutôt qu'une par date. Si vous mettez vous-même en cache les réponses de l'API, incluez la date de compatibilité dans la clé de cache pour les points de terminaison qui portent l'en-tête.

Ce qui compte comme changement incompatible ​

Les changements qui reçoivent une date et apparaissent dans le journal :

  • Supprimer ou renommer un champ d'une réponse
  • Changer le type ou la forme d'un champ existant
  • Rendre obligatoire un champ optionnel, ou toujours présent un champ omis
  • Changer le sens d'une valeur existante
  • Supprimer un point de terminaison ou changer sa sémantique

Les changements publiés sans version, parce qu'ils ne peuvent pas casser un client correct :

  • Ajouter un nouveau point de terminaison
  • Ajouter un nouveau paramètre de requête optionnel
  • Ajouter un nouveau champ à une réponse
  • Ajouter une nouvelle valeur à une énumération que vous ne faites que lire
  • Corrections de bugs alignant le comportement sur la documentation

Écrivez votre intégration de manière à ignorer les champs de réponse inconnus. Les changements additifs parviennent à toutes les versions, y compris la vôtre.

AstroAPI Documentation