Public vs private API sınırları

Bir organizasyonda birden fazla API yuzeyi bulunur: dis gelistiricilere açık public API, is ortaklari icin partner API ve yalnizca ic servisler arasi ileisimde kullanilan private API. Bu sinirlarin net tanimlanmamasi güvenlik aciklari, sözleşme karisikligi ve operasyonel yük üretir. Public ve private API'ler farklı tasarım, güvenlik ve yaşam dongusu gerektirir; ayni kod tabanindan farklı yuzeyler sunmak mümkün olsa da sözleşme ve politika ayrimi bilincli yapilmalidir.

Tanım ve kapsam

Public API internet uzerinden anonim veya kayitli dis tuketicilere açıktır. Dokumantasyon, SLA, versiyonlama ve destek surecleri ürün kalitesinde olmalidir. Private API kurum ic agi, VPN veya servis mesh uzerinde çalışır; dis erişim kapidir. Partner API arada bir modeldir: sinirli dis kitle, sözleşme ve özel credential.

Temel farklar

• Public: Geniş kitle, yavas değişim, geriye uyumluluk kritik.
• Private: Hızlı iterasyon, breaking change daha tolere edilir.
• Partner: Sözleşme bazli kota ve özel endpoint'ler.

Güvenlik modeli

Private API'ler network segmentation ile korunur: VPC, firewall ve mTLS. Public API'ler internet tehdit modeline karşı tasarlanir: OAuth2, rate limit, WAF ve DDoS korumasi zorunludur. Private API'de bazen auth hafifletilir; bu yanilticidir — ic tehdit ve lateral movement icin kimlik dogrulama yine gerekir.

# Public: OAuth2 + scope
Authorization: Bearer eyJhbGc...
# Internal: mTLS + service identity
X-Service-Identity: order-service

API ürün yönetimi

Public API bir urundur: developer portal, API key yönetimi, kullanım analitigi, changelog ve status page icerir. Private API operasyonel aractir; dokumantasyon ic wiki veya OpenAPI yeterli olabilir. Public API icin breaking change major versiyon ve deprecation takvimi zorunludur.

Developer experience

1. Kayıt ve credential self-service.
2. Sandbox ortami.
3. Örnek kod ve SDK.
4. Destek kanali ve SLA.

Versiyonlama ve yayın hizi

Private servisler gunluk deploy alabilir; tuketiciler ayni organizasyon icindedir ve koordinasyon kolaydir. Public API'de aylık veya ceyreklik release cycle ve uzun deprecation penceresi beklenir. Ayni domain modeli icin public /v2, internal /internal/v5 gibi ayri versiyon namespace kullanılabilir.

Veri ve alan modeli ayrimi

Public API ic veritabanı semasini veya ic alan adlarini aciga cikarmamali. DTO mapping ile hassas alanlar (maliyet, ic notlar, PII fazlasi) filtrelenir. Private API tam ic modeli dondurabilir. Anti-corruption layer public yuzeyi ic modelden ayirir.

// Public DTO
public record ProductPublicDto(Guid Id, string Name, decimal Price);
// Internal DTO
public record ProductInternalDto(..., decimal Cost, string SupplierCode);

Gateway ve routing ayrimi

Public trafik dis gateway uzerinden gecer; internal trafik ic gateway veya mesh uzerinden. Ayni servise iki farklı route ve politika uygulanir. Public route agresif rate limit ve WAF; internal route yüksek limit ve mTLS.

Observability ve audit

Public API erişim loglari compliance ve faturalandirma icin saklanir. Internal API loglari debug ve SLO icin yeterli olabilir. Her iki yuzeyde correlation ID zorunludur.

Partner API modeli

Is ortaklari icin ayri client credential, sinirli scope ve özel endpoint seti tanimlanir. Sözleşme bitince credential iptal edilir. Partner API public kadar açık degil, private kadar serbest degildir.

Strangler ve yuzey birlestirme

Bazi ekipler once internal API geliştirir, olgunlasinca public yuzey cikarir. Tersine public API'yi ic kullanım icin de acmak (dog-food) kaliteyi artirir. Iki yuzey ayni implementasyonu paylasabilir; controller veya route ayrimi ile farklı sözleşme sunulur.

Güvenlik anti-pattern'leri

Internal API'yi güvenlik duvari disina acmak, public endpoint'e ic alan birlestirmek, ayni API key'i public ve internal icin kullanmak yaygın hatalardir. Security through obscurity internal URL'lerin gizli kalacagi varsayimina dayanir; bu varsayim gecerlidir ama auth'i ikame etmez.

Maliyet ve kota

Public API kullanım bazli fiyatlandirma veya freemium kota ile yönetilir. Internal API maliyet merkezi dagitimi farklı hesaplanir. Public'te asiri kullanım gelir veya maliyet sorunu yaratir.

Test ve ortam ayrimi

Public sandbox üretim verisinden izole olmalidir. Internal test ortamlari üretim verisi kopyasi tasiyorsa erişim kisitli olmalidir. Partner test ortami ayri credential seti kullanır.

Hukuki ve uyumluluk

Public API kullanım kosullari, veri işleme sozlesmesi ve GDPR haklari dokumante edilir. Internal API çalışan ve sistem erisimi kapsamında degerlendirilir. Veri residency public tuketiciler icin bolgesel endpoint gerektirebilir.

Özet tasarım ilkeleri

Public ve private API sınırları güvenlik, sözleşme ve operasyon acisindan bilincli cizilmelidir. Ayni backend farklı DTO ve politika ile çoklu yuzey sunabilir. Public ürün kalitesinde dokumantasyon ve versiyon disiplini ister; private hiz ve ic entegrasyon odaklidir. Partner modeli arada kontrollu genisleme sağlar.

API gateway katmaninda route, auth ve limit ayrimi bu sınırları teknik olarak uygular. Anti-corruption layer ic modeli dis sozlesmeden korur. Developer portal ve sandbox public tarafta guven oluşturur; internal wiki ve mesh policy private tarafta yeterlidir.

Event ve webhook sınırları

Public webhook kayıt endpoint'i dis URL dogrulama ve imza gerektirir. Internal event bus mesajlari ag disina cikmaz. Partner webhook'lari ayri imza anahtari ve retry politikasi kullanır.

API analitigi ve ürün kararlari

Public API kullanım metrikleri hangi endpoint'lerin deger urettigini gösterir; deprecated alanlar düşük kullanımda kaldirilir. Internal API metrikleri performans darbogazini bulur. Iki metrik seti karistirilmamali.

Organizasyonel sahiplik

Public API icin product owner ve developer relations sahipligi net olmalidir. Private API icin platform veya domain ekibi sahiptir. Ayni ekibin her iki yuzeyi yonetmesi tutarlılık sağlar; farklı ekipler handoff dokumantasyonu gerektirir.

Gelecek: unified platform

API management platformlari public ve internal API'leri tek catalog'da listeler; visibility flag ile erişim ayrilir. Tek spec'ten çoklu yuzey üretmek drift riskini azaltir. Internal endpoint'ler x-internal: true extension ile isaretlenir ve public portalda gizlenir.

Veri siniflandirma

Her alan public, internal veya restricted olarak etiketlenir. Otomatik DTO uretimi bu etiketlere gore filtre uygular. Restricted alanlar log ve trace'de de maskelenir.

Incident response

Public API sizintisinda credential rotate, WAF kurali ve status page guncellemesi standart prosedurdur. Internal API olayinda ag izolasyonu ve servis restart yeterli olabilir. Playbook'lar ayri tutulur.

API tasarımında bu konu operasyonel olgunluk, ölçülebilir metrikler ve tuketici odaklı sözleşme yönetimi ile desteklenmelidir. Ekip icinde karar kayitlari, review surecleri ve otomatik testler kaliteyi sürdürülebilir kilar. Üretim verisi ve geri bildirim dongusu ile politika ve limit degerleri periyodik güncellenir.