Uygulamanız bir API sunacak. İki seçenek var: ayrı bir alt alan adı ya da mevcut sitenin altında bir klasör. Bu karar sonradan değiştirilmesi en pahalı kararlardan biridir, çünkü adres bir kez yayımlandığında entegrasyon yapan herkes ona bağımlı hâle gelir.
Bu yazı, API adres yapısı kararını ele alıyor.
İki Yaklaşım
| Konu | Alt alan adı | Klasör |
|---|---|---|
| Ayrı sunucuya taşıma | Kolay | Zor |
| Sertifika yönetimi | Ayrı gerekir | Aynısını kullanır |
| Çerez paylaşımı | Ayrık | Ortak |
| Kaynak paylaşım kuralları | Yapılandırma gerekir | Gerekmez |
| Bağımsız ölçekleme | Mümkün | Sınırlı |
| Kurulum kolaylığı | Ek adım | Hemen çalışır |
Birinci satır uzun vadeli kararın temelidir: alt alan adı kullanmak, API'yi ileride tamamen farklı bir sunucuya taşımanızı tek bir DNS değişikliğiyle mümkün kılar.
Klasör yapısında aynı taşıma, ters vekil sunucu yapılandırması gerektirir ve web sunucusu her istekte devrede kalır.
Üçüncü satır ise güvenlik açısından önemlidir ve sonraki bölümde ayrıca ele alınıyor.
Alt Alan Adının Güçlü Yanları
- Bağımsız altyapı. Farklı sunucu, farklı teknoloji.
- Ayrı ölçekleme. API yükü siteyi etkilemez.
- Net ayrım. Günlükler ve izleme ayrışır.
- Çerez yalıtımı. Güvenlik kazancı.
- Farklı güvenlik politikası.
Dördüncü madde çoğu tartışmada gözden kaçar ama önemli bir güvenlik avantajıdır: API ayrı bir alt alan adındaysa, tarayıcı site çerezlerini API isteklerine otomatik eklemez ve bu, belirli saldırı türlerini baştan imkânsız kılar.
Klasör yapısında ise API, sitenin oturum çerezlerini her istekte alır. Bu kolaylık gibi görünür ama ek koruma önlemleri gerektirir.
İkinci madde büyüyen sistemlerde belirleyici olur. API trafiği arttığında yalnızca o tarafı ölçeklendirmek mümkün olur.
Klasör Yapısının Güçlü Yanları
- Ek DNS kaydı gerekmez.
- Sertifika zaten kapsar.
- Tarayıcıdan çağırmak basittir.
- Küçük projelerde hızlı kurulur.
Üçüncü madde geliştirme hızını doğrudan etkiler: aynı alan adı altında olduğu için tarayıcıdan yapılan çağrılar kaynak paylaşım kısıtlarına takılmaz ve ek yapılandırma gerektirmez.
Bu, tek sayfa uygulamalarında ve hızlı prototiplerde gerçek bir kolaylıktır.
İkinci madde ise maliyet ve bakım tarafındadır. Ayrı bir sertifika almak ve yenilemek gerekmez.
Nasıl Karar Verilir?
| Durum | Öneri |
|---|---|
| Yalnızca kendi siteniz kullanacak | Klasör yeterli |
| Dışarıya açık API | Alt alan adı |
| Mobil uygulama kullanacak | Alt alan adı |
| Yüksek trafik bekleniyor | Alt alan adı |
| Küçük iç araç | Klasör |
İkinci satır kararın en net göstergesidir: API'yi dış geliştiricilere açacaksanız alt alan adı kullanın, çünkü o adres bir kez yayımlandıktan sonra yıllarca değiştirilemez.
Dışarıya verilen bir adresi değiştirmek, tüm entegrasyonların güncellenmesini beklemek demektir ve bu süre yıllarla ölçülür.
Beşinci satırda ise fazla mühendislik yapmamak gerekir. İç kullanıma yönelik küçük bir araç için ayrı alt alan adı kurmak gereksiz karmaşıklıktır.
Sürümleme
Adres yapısı kararı sürümlemeyi de içerir:
- Yol içinde sürüm. En yaygın yöntem.
- Alt alan adında sürüm. Tam ayrışma.
- Başlıkta sürüm. Adres sabit kalır.
Birinci yöntem en pratik olanıdır çünkü görünürdür: adresin içinde sürüm numarası taşımak, bir isteği görenin hangi sürümle konuşulduğunu anında anlamasını sağlar — günlüklerde, hata raporlarında ve destek yazışmalarında bu netlik değerlidir.
İkinci yöntem eski sürümü tamamen ayrı bir altyapıda çalıştırmayı mümkün kılar ama yönetilecek adres sayısını artırır.
Sürümleme kararı adres yapısıyla birlikte verilmelidir, çünkü ikisi birbirini kısıtlar.
DNS Tarafında Yapılacaklar
Alt alan adı tercih edilirse:
- Kaydı oluşturun. Adres kaydı veya takma ad.
- Sertifikaya dahil edin.
- Süre değerini planlayın.
- İzlemeye ekleyin.
Dördüncü madde sıkça atlanır: API alt alan adı ayrı bir adres olduğu için ana site izlemesi onun çalıştığını göstermez — ana sayfa açılıyor diye API'nin de yanıt verdiği varsayılamaz.
Bu ayrım, "site çalışıyor ama mobil uygulama bağlanamıyor" durumlarının nedenidir.
İkinci madde ise sertifika kapsamıyla ilgilidir. Joker sertifika kullanmıyorsanız, yeni alt alan adının sertifikaya eklenmesi gerekir.
Sık Yapılan Hatalar
| Hata | Sonuç |
|---|---|
| Adres yapısını sonradan değiştirmek | Entegrasyonlar kırılır |
| Test API'sini aynı adreste tutmak | Kaza riski |
| Sürüm planlamamak | Geriye uyum zorlaşır |
| Belgede farklı adres yazmak | Destek yükü |
İkinci satır ciddi kazalar üretir: test ve canlı API'nin benzer adresler kullanması, geliştiricinin yanlışlıkla canlı sisteme yazma yapmasına yol açar.
Adreslerin belirgin biçimde farklı olması bu riski azaltır. Yalnızca bir harf farkı yeterli değildir.
Alt alan adı planlarken kayıt ve DNS durumunuzu görmek için domain sorgulama hizmeti üzerinden mevcut ad sunucusu yapılandırmanızı kontrol edebilirsiniz.
Sonuç
API'yi dışarıya açacaksanız alt alan adı kullanın — o adres bir kez yayımlandıktan sonra yıllarca değiştirilemez ve alt alan adı ileride farklı bir sunucuya taşımayı tek bir DNS değişikliğine indirir. Alt alan adının gözden kaçan bir güvenlik avantajı da var: tarayıcı site çerezlerini API isteklerine otomatik eklemez. Sadece kendi siteniz kullanacaksa klasör yapısı fazlasıyla yeterlidir. Hangi yapıyı seçerseniz seçin, API adresini ana siteden ayrı izlemeye alın.
Sıkça Sorulan Sorular (SSS)
Hangisini seçmeliyim?
Dışarıya açık API, mobil uygulama kullanımı veya yüksek trafik bekleniyorsa alt alan adı. Yalnızca kendi siteniz kullanacaksa veya küçük bir iç araçsa klasör yapısı yeterlidir. Aşırı mühendislik yapmayın, ama dışarıya verilen adresi de sonradan değiştirmeye çalışmayın.
Alt alan adının güvenlik avantajı ne?
Tarayıcı, site çerezlerini farklı alt alan adına giden isteklere otomatik eklemez. Bu, belirli saldırı türlerini baştan imkânsız kılar. Klasör yapısında API sitenin oturum çerezlerini her istekte alır — kolaylık gibi görünür ama ek koruma önlemleri gerektirir.
Sürümlemeyi nasıl yapmalıyım?
En pratik yöntem sürüm numarasını adres yolunda taşımaktır çünkü görünürdür — bir isteği görenin hangi sürümle konuşulduğunu anında anlaması, günlüklerde ve destek yazışmalarında değerlidir. Sürümleme kararını adres yapısıyla birlikte verin, ikisi birbirini kısıtlar.
API'yi ayrı izlemeli miyim?
Evet. Alt alan adı ayrı bir adres olduğu için ana site izlemesi onun çalıştığını göstermez. "Site çalışıyor ama mobil uygulama bağlanamıyor" durumlarının nedeni tam olarak budur.
