Versionado de la API
AstroAPI versiona los cambios incompatibles con una fecha de compatibilidad en lugar de un número de versión en la URL. Las rutas de los endpoints nunca cambian; usted fija una fecha y sigue recibiendo exactamente el comportamiento vigente en esa fecha.
Su versión
Envíe la fecha de compatibilidad contra la que ha desarrollado en la cabecera X-Api-Version:
GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01Una respuesta moldeada por una fecha de compatibilidad le indica cuál:
X-Api-Version: 2026-01-01
Vary: X-Api-VersionLos endpoints cuya salida no depende de la versión omiten ambas cabeceras. GET /api/modules devuelve el mismo cuerpo en cualquier fecha, así que no hay nada que informar ni nada que una caché deba mantener separado. Si envía un X-Api-Version explícito, se le devuelve en cualquier endpoint, de modo que siempre puede confirmar que un valor fue aceptado.
Para leer la versión a la que se resuelve su organización, use GET /api/org/api-version; su effectiveApiVersion es la fecha que se aplica cuando una petición no lleva cabecera propia.
Si no envía cabecera, las peticiones usan la versión fijada de su organización y, si no ha fijado ninguna, la línea base de 2026-01-01. El comportamiento nuevo nunca se le aplica automáticamente: una integración escrita hoy sigue funcionando igual sin importar lo que publiquemos después.
Registro de cambios
Cada cambio incompatible se enumera aquí con la fecha en que entra en vigor. Fijar una fecha le da todos los cambios en esa fecha o anteriores.
| Fecha | Cambio |
|---|---|
2026-09-03 | aspects en POST /api/calc/transit está agrupado: una entrada por planeta en tránsito, aspecto y planeta natal, con el texto de interpretación una sola vez y cada pasada del período bajo occurrences. Antes había una entrada por pasada, repitiendo el texto. Consulte Tránsitos. |
2026-09-10 | Cada punto de POST /api/calc/natal lleva declination (grados, norte positivo) y outOfBounds (más allá de la declinación máxima del Sol para esa fecha). Antes ninguno de los dos campos estaba presente. Consulte Declinaciones. |
La línea base 2026-01-01 es la versión más antigua que servimos. Fijar una fecha anterior se acepta y se resuelve a la línea base.
Fijar su organización
En lugar de añadir una cabecera a cada llamada, fije su organización una vez. Todas las peticiones sin versión usarán entonces esa fecha.
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" }
}
}'Lea la fijación actual, junto con el rango entre el que puede elegir:
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"
}
}
}Envíe "apiVersion": null para borrar la fijación y volver a la línea base.
Actualizar con seguridad
La cabecera siempre gana a la fijación de la organización, lo que hace posible un despliegue seguro:
- Lea el registro de cambios anterior y compruebe qué cambios caen entre su fecha actual y la nueva.
- Envíe la nueva fecha en
X-Api-Versionen unas cuantas peticiones, o en su entorno de pruebas, y verifique las respuestas. - Cuando esté satisfecho, fije su organización a la nueva fecha y vuelva a omitir la cabecera.
Como la cabecera anula la fijación por petición, también puede hacer lo contrario: fijar su organización hacia delante y enviar temporalmente una fecha anterior desde un servicio que aún no haya migrado.
Clientes de navegador e incrustaciones
Los contextos que no pueden establecer cabeceras de petición — incrustaciones <img>, <iframe> y <script>, URLs de carta firmadas — aceptan la fecha como parámetro de consulta:
https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...La cabecera tiene prioridad cuando ambas están presentes. Para fetch() y XHR, use la cabecera; X-Api-Version está permitida por CORS y se expone en las respuestas, de modo que puede leer qué versión se aplicó.
Validación
Un valor mal formado devuelve 400 Bad Request en lugar de caer en silencio a otra opción:
{
"error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}El valor debe ser una fecha de calendario real en formato YYYY-MM-DD. Una fecha bien formada fuera del rango admitido se ajusta en lugar de rechazarse: anterior a la línea base se resuelve a la línea base; posterior al cambio más reciente se resuelve al comportamiento más reciente.
Caché
Las respuestas cuyo cuerpo puede diferir por versión se marcan con Vary: X-Api-Version, de modo que una caché compartida o una CDN delante de su integración mantendrá esas versiones separadas. Las respuestas iguales en cualquier fecha no llevan Vary, lo que permite que una caché sirva una sola entrada para todos sus clientes en lugar de una por fecha. Si usted mismo cachea respuestas de la API, incluya la fecha de compatibilidad en la clave de caché para los endpoints que llevan la cabecera.
Qué cuenta como cambio incompatible
Cambios que reciben una fecha y aparecen en el registro:
- Eliminar o renombrar un campo de una respuesta
- Cambiar el tipo o la forma de un campo existente
- Hacer obligatorio un campo opcional, o siempre presente un campo omitido
- Cambiar el significado de un valor existente
- Eliminar un endpoint o cambiar su semántica
Cambios que se publican sin versión, porque no pueden romper un cliente correcto:
- Añadir un endpoint nuevo
- Añadir un parámetro de petición opcional nuevo
- Añadir un campo nuevo a una respuesta
- Añadir un valor nuevo a un enum que usted solo lee
- Correcciones que alinean el comportamiento con la documentación
Escriba su integración de modo que ignore los campos de respuesta desconocidos. Los cambios aditivos llegan a todas las versiones, incluida la suya.