Namaz vakti gösteren bir uygulama yapıyorsanız er ya da geç şu soruyla karşılaşırsınız: gösterdiğiniz vakitler Diyanet'in yayınladığı takvimle birebir uyuşuyor mu? Hesaplama tabanlı servisler yöntem parametresine göre birkaç dakika sapabilir ve kullanıcı bu farkı fark eder. Resmi takvimle aynı olmak gerekiyorsa kaynak da resmi olmalıdır.
Diyanet AwqatSalah tam olarak bu ihtiyaç için vardır. Ancak anahtarsız çalışan alternatiflerinden farklı olarak başvuru, kimlik doğrulama ve token yönetimi ister. Bu yazı, hangi API'yi seçeceğinizi değil, AwqatSalah'ı seçtikten sonra doğru şekilde nasıl entegre edeceğinizi anlatır. Seçim aşamasındaysanız önce namaz vakti API'leri karşılaştırmasına bakmanız daha faydalı olur.
Entegrasyonun genel şekli
AwqatSalah entegrasyonu dört adımdan oluşur ve bu sıra değişmez:
1. Başvuru ve hesap oluşturma 2. Kimlik bilgileriyle giriş yapıp erişim token'ı alma 3. Ülke, şehir ve ilçe kimliklerini çözme 4. İlçe kimliğiyle vakit verisini çekme
Bu adımların üçüncüsü çoğu geliştiricinin gözden kaçırdığı yerdir. Vakit isteyen uç nokta şehir adı kabul etmez, sayısal bir kimlik ister. O kimliği bulmak için ayrı bir keşif akışı kurmanız gerekir.
Adım 1 — Başvuru ve erişim
AwqatSalah anonim erişime kapalıdır. Resmi başvuru sayfasından hesap oluşturmanız ve size verilen kimlik bilgilerini almanız gerekir. Bu, servisi anahtarsız alternatiflerden ayıran ilk maliyettir: prototipe beş dakikada başlayamazsınız.
Kimlik bilgilerini koda gömmeyin. Sunucu tarafında ortam değişkeni olarak tutun ve istemciye asla göndermeyin. Namaz vakti verisi hassas olmasa da hesap kimlik bilgileriniz hassastır; tarayıcıya düşen bir kullanıcı adı/parola çifti başkalarının sizin kotanızı tüketmesine yol açar.
Bu, mimari açıdan önemli bir kısıt doğurur: AwqatSalah'ı doğrudan tarayıcıdan veya mobil uygulamadan çağıramazsınız. Kendi sunucunuzda bir ara katman kurup, istemcinin sizin uç noktanıza konuşmasını sağlamanız gerekir. Anahtarsız alternatiflerde bu katman opsiyoneldir, burada zorunludur.
Adım 2 — Token yaşam döngüsü
Giriş isteği başarılı olduğunda size bir erişim token'ı ve bir yenileme token'ı döner. Erişim token'ı sınırlı ömürlüdür; süresi dolduğunda yenileme token'ı ile yeni bir tane alırsınız.
Buradaki en yaygın hata, token'ı her istekte yeniden almaktır. Bu hem gereksiz yük yaratır hem de giriş uç noktasının oran sınırına takılmanıza yol açar. İkinci yaygın hata ise token'ı süresiz varsaymak ve süre dolduğunda uygulamanın sessizce boş veri göstermesidir.
Doğru yaklaşım, token'ı bellekte tutan ve 401 yanıtına tepki veren küçük bir istemci yazmaktır:
let cachedToken: { value: string; expiresAt: number } | null = null;
async function getToken(): Promise<string> {
const now = Date.now();
if (cachedToken && cachedToken.expiresAt > now + 60_000) {
return cachedToken.value;
}
const token = await login();
cachedToken = { value: token.accessToken, expiresAt: token.expiresAt };
return cachedToken.value;
}
async function request<T>(path: string, retry = true): Promise<T> {
const response = await fetch(`${BASE_URL}${path}`, {
headers: { Authorization: `Bearer ${await getToken()}` },
});
if (response.status === 401 && retry) {
cachedToken = null;
return request<T>(path, false);
}
if (!response.ok) {
throw new Error(`AwqatSalah isteği başarısız (${response.status}) — ${path}`);
}
return response.json() as Promise<T>;
}Bu yapıdaki iki ayrıntı önemlidir. Birincisi, token'ın süresi dolmadan bir dakika önce yenilenmesi; sınırda kalan istekler yarış durumuna girmesin diye. İkincisi, 401 sonrası yalnızca bir kez yeniden deneme yapılması; kimlik bilgileri gerçekten geçersizse sonsuz döngüye girmemek için.
Sunucunuz birden fazla süreçte çalışıyorsa token'ı süreç belleğinde değil, paylaşılan bir yerde (örneğin Redis) tutmak daha verimlidir. Aksi halde her süreç ayrı token alır ve giriş uç noktasına gereksiz yük binersiniz.
Adım 3 — Ülke, şehir ve ilçe kimlikleri
Vakit uç noktaları yer adı değil, sayısal kimlik ister. Bu kimlikleri servis kendi hiyerarşisi üzerinden verir: önce ülkeler, seçilen ülkenin şehirleri, seçilen şehrin ilçeleri.
Bu listeler pratikte neredeyse hiç değişmez. Her kullanıcı isteğinde bu üç seviyeyi yeniden sorgulamak, çözdüğünüz problemin kat kat üzerinde bir maliyet yaratır. Doğru yaklaşım, listeleri periyodik olarak çekip kendi veritabanınızda saklamaktır.
Kendi tarafınızda tutarken, kullanıcı arayüzünde arama yapılabilmesi için ilçe adlarını Türkçe karakter duyarsız aranabilir bir alanla birlikte saklayın. "Çankaya" arayan kullanıcı "cankaya" yazdığında da sonucu bulmalıdır. Bu küçük ayrıntı, il/ilçe seçim ekranının kullanılabilirliğini doğrudan belirler.
Kullanıcının seçimini de ilçe adıyla değil, ilçe kimliğiyle saklayın. Adlar değişebilir, birleşebilir veya farklı yazımlarla gelebilir; kimlik sabittir.
Adım 4 — Vakit verisini çekmek ve saklamak
Servis günlük, haftalık ve aylık vakit verisi sunar. Hangisini kullanacağınız ekranınıza bağlıdır ama neredeyse her durumda doğru cevap "aylık"tır.
Nedeni basit: aylık veri tek istekte otuz günü getirir. Kullanıcı bugünün vakitlerini görürken, yarının ve haftaya cumanın vakitlerini de elinizde tutmuş olursunuz. Günlük uç noktayı her gün çağırmak, aynı bilgiyi otuz ayrı istekte almak demektir.
Aylık veriyi çektikten sonra ilçe ve ay bazında saklayın. Vakitler geçmişe dönük değişmediği için bu kayıtların geçerliliği uzundur. Ay değiştiğinde veya kayıt bulunamadığında yeniden çekmek yeterlidir.
Sakladığınız kayda mutlaka iki alan ekleyin: veriyi hangi tarihte çektiğiniz ve kaynağın ne olduğu. Kullanıcıya "kaynak: Diyanet, güncelleme: 1 Ağustos" bilgisini gösterebilmek, hem güven verir hem de bir sorun olduğunda hata ayıklamayı kolaylaştırır.
Saat dilimi tuzağı
Namaz vakti uygulamalarında en sık görülen hata saat dilimi kaynaklıdır ve sinsi ilerler: geliştirme ortamınızda doğru çalışır, sunucuya çıktığınızda vakitler kayar.
Sorunun kaynağı şudur: sunucunuz büyük olasılıkla UTC saat diliminde çalışır, vakit verisi ise yerel saate göre gelir. Gelen "05:42" değerini sunucunun yerel saatiyle yorumlarsanız üç saat kayma alırsınız.
Çözüm, vakit değerlerini mutlak zaman damgasına dönüştürürken tarihi ve hedef şehrin saat dilimini birlikte kullanmaktır. "Bugün hangi vakitteyiz" hesabını yaparken de sunucunun saatini değil, kullanıcının seçtiği ilçenin saat dilimini esas alın. Türkiye içi uygulamalarda tek saat dilimi olduğu için bu fark gizli kalabilir, ancak yurt dışındaki kullanıcılar için hemen ortaya çıkar.
Gün dönümü de ayrı bir ayrıntıdır. Yatsıdan sonra "sonraki vakit" imsaktır ve bu, ertesi güne aittir. Bu geçişi ele almayan kod gece yarısından sonra boş ekran gösterir.
Sık yapılan hatalar
Token'ı istemciye göndermek. Erişim token'ını tarayıcıya iletip istekleri oradan atmak, hesabınızı üçüncü kişilere açar. Ara katman zorunludur.
Süresi dolmuş token'ı fark etmemek. 401 yanıtını hata olarak loglayıp kullanıcıya boş ekran göstermek yerine, token'ı tazeleyip isteği tekrarlayın.
Her istekte hiyerarşiyi yeniden çözmek. Ülke/şehir/ilçe listeleri statik sayılır; her seferinde çekmek gereksiz maliyettir.
Vakitleri ilçe adıyla eşleştirmek. Ad yerine kimlik kullanın.
Tek kaynağa geri dönüşsüz bağlanmak. Servis geçici olarak yanıt vermediğinde uygulamanızın ne göstereceğini baştan kararlaştırın. Son başarılı veriyi "önbellekten, X tarihinde alındı" notuyla göstermek, hata ekranı göstermekten iyidir.
Ne zaman alternatife geçmeli?
AwqatSalah'ın maliyeti başvuru ve token yönetimidir. Bu maliyet, resmi veri gerekliliği olan projelerde makuldür. Ancak her proje bu gerekliliğe sahip değildir.
Global bir uygulama yapıyor ve dünyanın herhangi bir şehri için vakit gösteriyorsanız AlAdhan hem anahtarsız hem de coğrafi olarak çok daha geniştir. Türkiye odaklı ama resmi veri zorunluluğu olmayan bir uygulamada İmsakiyem il/ilçe akışıyla daha hızlı sonuç verir.
Karşılaştırmalı değerlendirme için namaz vakti, imsak ve iftar API'leri yazısı bu üç seçeneği yan yana ele alıyor.
Bu rehberdeki akış ve davranış açıklamaları resmi dokümantasyona dayanır. Uç nokta yolları ve token süreleri sağlayıcı tarafından güncellenebildiği için, entegrasyona başlamadan önce resmi dokümandaki güncel değerleri doğrulayın.
İlgili API Deposu kayıtları
Kaynaklar
Sık Sorulan Sorular
›Diyanet AwqatSalah API'si ücretsiz mi?
Servis başvuru ve kimlik doğrulama ile erişime açılır. Ücretlendirme ve kullanım koşulları Diyanet tarafından belirlenir; başvuru öncesinde resmi sayfadaki güncel koşulları okumanız gerekir.
›Token ne kadar sürede geçersiz oluyor?
Erişim token'ı sınırlı ömürlüdür ve süresi dolduğunda yenileme token'ı ile tazelenir. Kesin süreyi resmi dokümandan doğrulayın; kodunuzu sabit bir süreye değil, 401 yanıtına tepki verecek şekilde kurun.
›İl ve ilçe kimliklerini nasıl buluyorum?
Servis ülke, şehir ve ilçe listelerini ayrı uç noktalardan verir. Bu listeler nadiren değiştiği için uygulama açılışında bir kez çekip kendi tarafınızda saklamanız, her istekte yeniden sorgulamaktan çok daha verimlidir.
›Resmi Diyanet verisi ile hesaplama tabanlı API'ler arasında fark olur mu?
Evet. AlAdhan gibi servisler vakitleri seçilen hesaplama yöntemine göre üretir; Diyanet ise kendi resmi takvimini yayınlar. Aynı şehir için birkaç dakikalık farklar görülebilir. Resmi takvimle birebir uyum gerekiyorsa Diyanet kaynağı tercih edilmelidir.
›Vakitleri kendi veritabanımda saklayabilir miyim?
Teknik olarak mümkündür ve cache açısından önerilir, ancak verinin yeniden dağıtımı kullanım koşullarına tabidir. Ticari bir üründe saklama ve paylaşma sınırlarını başvuru sırasında netleştirin.