Geliştirici Dokümantasyonu
Geliştiriciler
Holiday Lydian platformu için API'ye genel bakış, kimlik doğrulama modeli, hız limitleri ve hata kataloğu.
Mevcut durum
Burada anlatılan HTTP API'si birinci taraftır: kendi web ve mobil istemcilerimizi çalıştırır ve aynı köken (same-origin) oturumuyla kimlik doğrulaması yapar. Kamuya açık bir API anahtarı programı ve yayımlanmış bir SDK yol haritamızdadır ve henüz genel kullanıma sunulmamıştır. Bir entegrasyon geliştiriyorsanız bizimle iletişime geçin, erişimi birlikte planlayalım.
API'ye genel bakış
Platform, HTTPS üzerinden JSON tabanlı bir API sunar. Uç noktalar REST kurallarını izler: kaynaklara yol (path) ile erişilir, sonuçlar JSON olarak döner ve başarı ya da başarısızlık standart HTTP durum kodlarıyla bildirilir. Tüm trafik, holiday.ailydian.com kökeninden TLS üzerinden sunulur.
| Yöntem | Uç nokta | Amaç |
|---|---|---|
| GET | /api/health | Servis sağlık kontrolü. |
| GET | /api/tours | Turları destinasyona göre listeler ve filtreler. |
| GET | /api/search/hotels | Otelleri destinasyon ve tarihe göre arar. |
| GET | /api/transfers/search | Havalimanı ve şehirlerarası transferleri arar. |
| GET | /api/search/cars | Araç kiralama uygunluğunu arar. |
Kimlik doğrulama
Bugün, kimlik doğrulaması gerektiren uç noktalar giriş sırasında verilen aynı köken oturum çerezine dayanır. İstemciler birinci taraf olduğundan istekler oturumu otomatik taşır; API anahtarı gerekmez ve kabul edilmez. Siteler arası istekler reddedilir ve değişiklik yapan istekler CSRF korumalıdır.
Yol haritası: Üçüncü taraf entegrasyonlar için uzun ömürlü API anahtarları ve OAuth tarzı kapsamlı (scoped) token'lar planlanmaktadır. Kullanıma sunulduğunda kuruluş başına, kapsam bazlı izinlerle verilecektir.
Hız limitleri
Platform kararlılığını korumak için istekler istemci başına hız sınırlamasına tabidir. Bir istemci payını aştığında API, HTTP 429 ve ne zaman yeniden deneneceğini belirten bir Retry-After başlığı döner. Uç noktayı zorlamak yerine geri çekilip yeniden deneyen istemciler geliştirin.
- 429 yanıtı yavaşlama demektir — Retry-After başlığına uyun.
- Yeniden denemeler için jitter'lı üstel geri çekilme (exponential backoff) kullanın.
- Mümkün olduğunda okuma yanıtlarını önbelleğe alın; katalog verileri seyrek değişir.
Hata kataloğu
Hatalar, 2xx dışında bir HTTP durumu ve makine tarafından okunabilir sabit bir kod ile insan tarafından okunabilir bir mesaj içeren JSON gövde döner. Mesaj metnine değil koda göre eşleştirin.
| Durum | Kod | Anlamı |
|---|---|---|
| 400 | bad_request | İstek hatalı biçimlendirilmiş ya da zorunlu parametreler eksik. |
| 401 | unauthenticated | Geçerli bir oturum sağlanmadı; önce giriş yapın. |
| 403 | forbidden | Kimlik doğrulandı ancak bu kaynağa erişim izni yok. |
| 404 | not_found | İstenen kaynak mevcut değil. |
| 405 | method_not_allowed | Bu uç noktada bu HTTP yöntemi desteklenmiyor. |
| 422 | validation_error | İstek gövdesi doğrulamadan geçemedi; ayrıntılar için mesaja bakın. |
| 429 | rate_limited | Çok fazla istek — Retry-After'da belirtilen süre sonra yeniden deneyin. |
| 500 | internal_error | Sunucuda beklenmeyen bir hata oluştu. |
Örnek istek ve yanıt
İstek
curl -sS 'https://holiday.ailydian.com/api/tours?destination=antalya&limit=2' \
-H 'Accept: application/json'Yanıt
{
"success": true,
"count": 2,
"results": [
{
"slug": "antalya-city-tour",
"title": "Antalya City Tour",
"destination": "antalya",
"priceFrom": 39,
"currency": "USD"
}
]
}Tam alan kümesi uç noktaya göre değişir. Zamanla alanlar eklenebilir; bilinmeyen alanları yok sayan istemciler yazın.
SDK'lar
Bugün yayımlanmış bir istemci SDK'sı yoktur. HTTP istemcisi olan herhangi bir dil API'yi doğrudan çağırabilir. Resmi bir SDK, yol haritasındaki kamuya açık API anahtarı programının ardından gelecektir.
İletişim
Bir entegrasyon mu planlıyorsunuz ya da erken API erişimine mi ihtiyacınız var? Bize e-posta gönderin, kapsamını belirlemenize yardımcı olalım.
developers@holiday.ailydian.com
Bunun yerine envanter mi sağlıyorsunuz? Tedarikçi başvurusuna göz atın.