API Sürümleme
AstroAPI, geriye dönük uyumsuz değişiklikleri URL'deki bir sürüm numarası yerine bir uyumluluk tarihi ile sürümler. Uç nokta yolları asla değişmez; bir tarih sabitlersiniz ve o tarihte geçerli olan davranışı tam olarak almaya devam edersiniz.
Sürümünüz
Geliştirme yaptığınız uyumluluk tarihini X-Api-Version başlığında gönderin:
GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01Bir uyumluluk tarihiyle şekillendirilmiş bir yanıt size hangisi olduğunu söyler:
X-Api-Version: 2026-01-01
Vary: X-Api-VersionÇıktısı sürüme bağlı olmayan uç noktalar her iki başlığı da atlar. GET /api/modules her tarihte aynı gövdeyi döndürür, dolayısıyla bildirilecek bir şey ve bir önbelleğin ayrı tutması gereken bir şey yoktur. Açık bir X-Api-Version gönderirseniz, herhangi bir uç noktada size geri yansıtılır; böylece bir değerin kabul edildiğini her zaman doğrulayabilirsiniz.
Kuruluşunuzun hangi sürüme çözümlendiğini geri okumak için GET /api/org/api-version kullanın; onun effectiveApiVersion değeri, bir isteğin kendi başlığı olmadığında geçerli olan tarihtir.
Başlık göndermezseniz, istekler kuruluşunuzun sabitlenmiş sürümünü, hiçbir sürüm sabitlemediyseniz 2026-01-01 temel sürümünü kullanır. Yeni davranış size asla otomatik olarak uygulanmaz — bugün yazılan bir entegrasyon, sonradan ne yayınlarsak yayınlayalım değişmeden çalışmaya devam eder.
Değişiklik günlüğü
Her uyumsuz değişiklik burada yürürlüğe girdiği tarihle listelenir. Bir tarih sabitlemek size o tarihteki ve daha önceki tüm değişiklikleri verir.
| Tarih | Değişiklik |
|---|---|
2026-09-03 | POST /api/calc/transit üzerindeki aspects gruplandırıldı: transit gezegen, açı ve doğum haritası gezegeni başına bir kayıt; yorum metni bir kez ve dönemdeki her geçiş occurrences altında. Önceden her geçiş için ayrı bir kayıt vardı ve her biri aynı metni tekrarlıyordu. Bkz. Transitler. |
2026-09-10 | POST /api/calc/natal üzerindeki her nokta declination (derece, kuzey pozitif) ve outOfBounds (o tarih için Güneş'in azami deklinasyonunun ötesinde) taşır. Önceden bu alanların hiçbiri yoktu. Bkz. Deklinasyonlar. |
2026-01-01 temel sürümü sunduğumuz en eski sürümdür. Daha önceki bir tarihi sabitlemek kabul edilir ve temel sürüme çözümlenir.
Kuruluşunuzu sabitleme
Her çağrıya bir başlık eklemek yerine, kuruluşunuzu bir kez sabitleyin. Sürümsüz tüm istekler o zaman bu tarihi kullanır.
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" }
}
}'Mevcut sabitlemeyi, seçebileceğiniz aralıkla birlikte geri okuyun:
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"
}
}
}Sabitlemeyi kaldırıp temel sürüme dönmek için "apiVersion": null gönderin.
Güvenli yükseltme
Başlık her zaman kuruluş sabitlemesini yener; bu da güvenli bir yayına geçişi mümkün kılar:
- Yukarıdaki değişiklik günlüğünü okuyun ve mevcut tarihiniz ile yeni tarih arasında hangi değişikliklerin kaldığını kontrol edin.
- Yeni tarihi birkaç istekte veya hazırlık ortamınızda
X-Api-Versioniçinde gönderin ve yanıtları doğrulayın. - Memnun kaldığınızda kuruluşunuzu yeni tarihe sabitleyin ve başlığı tekrar kaldırın.
Başlık, sabitlemeyi istek bazında geçersiz kıldığından tersini de yapabilirsiniz: kuruluşunuzu ileri bir tarihe sabitleyip henüz taşımadığınız bir servisten geçici olarak daha eski bir tarih gönderin.
Tarayıcı ve gömme istemcileri
İstek başlığı ayarlayamayan bağlamlar — <img>, <iframe> ve <script> gömmeleri, imzalanmış harita URL'leri — tarihi bunun yerine sorgu parametresi olarak kabul eder:
https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...İkisi de mevcut olduğunda başlık önceliklidir. fetch() ve XHR için başlığı kullanın; X-Api-Version CORS tarafından izinlidir ve yanıtlarda açığa çıkarılır, böylece hangi sürümün uygulandığını geri okuyabilirsiniz.
Doğrulama
Hatalı biçimli bir değer sessizce geri düşmek yerine 400 Bad Request döndürür:
{
"error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}Değer, YYYY-MM-DD biçiminde gerçek bir takvim tarihi olmalıdır. Desteklenen aralığın dışındaki iyi biçimli bir tarih reddedilmek yerine sınırlandırılır: temel sürümden erken olan temel sürüme, en son değişiklikten geç olan en son davranışa çözümlenir.
Önbellekleme
Gövdesi sürüme göre farklılaşabilen yanıtlar Vary: X-Api-Version ile işaretlenir; böylece entegrasyonunuzun önündeki paylaşılan bir önbellek veya CDN bu sürümleri ayrı tutar. Her tarihte aynı olan yanıtlar Vary taşımaz; bu da bir önbelleğin tarih başına bir giriş yerine tüm çağıranlarınız için tek bir giriş sunmasını sağlar. API yanıtlarını kendiniz önbelleğe alıyorsanız, başlığı taşıyan uç noktalar için uyumluluk tarihini önbellek anahtarına dahil edin.
Neler uyumsuz değişiklik sayılır
Tarih alan ve günlükte görünen değişiklikler:
- Bir yanıttaki alanı kaldırmak veya yeniden adlandırmak
- Mevcut bir alanın türünü veya biçimini değiştirmek
- İsteğe bağlı bir alanı zorunlu, atlanan bir alanı her zaman mevcut hale getirmek
- Mevcut bir değerin anlamını değiştirmek
- Bir uç noktayı kaldırmak veya anlamını değiştirmek
Sürümsüz yayınlanan değişiklikler; çünkü doğru bir istemciyi bozamazlar:
- Yeni bir uç nokta eklemek
- Yeni bir isteğe bağlı istek parametresi eklemek
- Bir yanıta yeni bir alan eklemek
- Yalnızca okuduğunuz bir enum'a yeni bir değer eklemek
- Davranışı belgelerle uyumlu hale getiren hata düzeltmeleri
Entegrasyonunuzu bilinmeyen yanıt alanlarını yok sayacak şekilde yazın. Ekleyici değişiklikler sizinki dahil her sürüme ulaşır.