API'yi bir ürüne çeviren şey geliştirici portalı değil, arkasında duran dört sözleşme: şema, hata biçimi, kimlik doğrulama ve kota. Bu dördü yazılı ve sürümlü değilse sattığınız şey bir API değil, her müşteri için ayrı bakım gerektiren bir entegrasyondur. Aşağıdaki başlıklar, o dört sözleşmenin bugün hangi standartla kurulduğunu ve Türkiye'de hangi yükümlülüğe bağlandığını anlatıyor.
Bu yazı API'yi dışarıya açan ekipler için. Kendi API'nizi saldırıya karşı sertleştirme tarafını API güvenliği yazısında ayrı ele aldık; burada güvenlikten yalnızca ürün kararını etkileyen kısmı var.
Şema Sözleşmesi: Sürüm Numarasının Anlamı Sandığınızdan Dar
OpenAPI Specification'ın 10 Eylül 2026 tarihli sürümü 3.2.1. Spesifikasyonun kendi kuralı, sürüm numarasını nasıl okumanız gerektiğini söylüyor: major.minor kısmı özellik kümesini belirler, .patch ise yalnızca dokümandaki hataları düzeltir veya açıklık getirir (bkz. OpenAPI Specification v3.2.1).
Aynı metin araç geliştiricilerine de bir kural koyuyor: OAS 3.1'i destekleyen bir araç tüm 3.1.* sürümleriyle uyumlu olmalı ve patch sürümünü dikkate almamalı. Yani 3.1.0 ile 3.1.1 arasında ayrım yapan bir doğrulayıcı kullanıyorsanız, sorun sizin şemanızda değil aracınızda.
Pratik sonucu şu: şema dosyanızı elle yazılmış dokümantasyonun yanında bir ek olarak tutmayın. Şemayı kaynak kabul edin, istemci kütüphanesini ve dokümantasyonu ondan üretin, ve şema değişikliğini sürüm kontrolünde bir inceleme (review) adımına bağlayın. Şemanın koddan sonra güncellendiği her ekipte, üç ay içinde ikisi ayrışıyor.
Hata Sözleşmesi Olmayan API Faturalandırılamaz
Bu, Türkçe API ekonomisi içeriğinde neredeyse hiç geçmeyen ama destek maliyetini doğrudan belirleyen kısım. Müşteriniz 400 aldığında ne yapacağını bilmiyorsa, sizin destek ekibinize yazıyor. Yüz müşteride bu bir ürün değil, bir çağrı merkezi.
Standart hazır: RFC 9457, "Problem Details for HTTP APIs", Temmuz 2023'te Standards Track olarak yayımlandı ve RFC 7807'yi yürürlükten kaldırdı (bkz. RFC 9457). Medya tipleri application/problem+json ve application/problem+xml.
Tanımlı üyeler ve hepsinin isteğe bağlı olduğu bilgisi işin püf noktası:
type: sorun tipini tanımlayan URI. Varsayılanıabout:blank; yani boş bırakılan bir gövde hâlâ geçerlidir, ama hiçbir işe yaramaz.title: insan okunur kısa başlık. Aynıtypeiçin sabit kalmalı.status: HTTP durum kodu. Gövdedeki değerle başlıktaki kodun ayrışması, en sık görülen ayrıştırıcı hatası.detail: bu örneğe özgü açıklama. Genel tipi anlatmak için değil, bu isteğin neden reddedildiğini söylemek için.instance: sorunun belirli oluşumunu tanımlayan URI.
Buradaki tasarım kararı type URI'lerini kendi dokümantasyonunuzda gerçek bir sayfaya işaret ettirmek. Müşteri hata gövdesindeki adresi tıkladığında ne yapacağını okuyorsa, o çağrı size gelmiyor.
Kimlik Doğrulama: OAuth 2.1 Henüz RFC Değil, Ama Kuralları Bugün Geçerli
Bu ayrımı bilmek şartname yazarken işe yarıyor. OAuth 2.1, RFC 6749 ile RFC 6750'yi konsolide eden bir çalışma ve hâlâ Internet-Draft statüsünde: 3 Eylül 2026 tarihli draft-ietf-oauth-v2-1-16 (bkz. draft-ietf-oauth-v2-1). Şartnameye "OAuth 2.1 uyumlu olacaktır" yazarken taslak numarasını da yazın; aksi hâlde neye uyulacağı belirsiz kalır.
Taslağın getirdiği dört kesin değişiklik, yeni bir API açıyorsanız bugünden uygulanmalı:
- PKCE zorunlu. Yetkilendirme kodu akışının tamamında, gizli istemciler dahil.
- Implicit grant kaldırıldı. Tarayıcı içi uygulamalar için hâlâ implicit anlatan bir entegrasyon dokümanı alıyorsanız, o doküman bakımsız.
- Resource Owner Password Credentials kaldırıldı. Kullanıcı adı ve parolayı istemciden geçiren akış yok.
- Redirect URI tam eşleşme. Loopback adresleri dışında joker veya önek eşleşmesi yok.
Dördüncü madde en çok geri dönüş üreteni. Bir müşterinin her ortamı için ayrı redirect URI kaydı gerekiyor demektir; bunu istemci kayıt akışınıza baştan koymazsanız, her müşteri entegrasyonunda elle iş çıkar.
Fiyatlandırma Modelini Kota Mimariniz Belirliyor
"Freemium mi, kullandıkça öde mi, abonelik mi" tartışması mimariden bağımsız yapılamaz. Ölçemediğiniz şeyi faturalandıramazsınız ve ölçüm birimi, kota sayacınızın ne saydığına bağlı.
İşlem başına fiyatlandırmanın olgun bir örneği Stripe: ABD'de standart kart işlemi %2,9 + 30 sent, uluslararası kartta +%1,5, para birimi çevrimi gerekiyorsa +%1, ACH ödemelerinde %0,8 ve işlem başına 5 USD tavan (bkz. Stripe Pricing). Dikkat edilecek şey oranlar değil, yapı: fiyat çağrı sayısına değil işlenen değere bağlı ve ek maliyet kalemleri ayrı satırlar hâlinde görünüyor.
Kendi API'niz için karar kuralı:
| API'nin doğası | Ölçüm birimi | Gereken altyapı |
|---|---|---|
| Her çağrının maliyeti benzer (arama, doğrulama) | Çağrı sayısı | Uç bazında sayaç + aylık toplam |
| Çağrı maliyeti çok değişken (rapor, toplu işlem) | Ağırlıklı kredi | Uç başına ağırlık tablosu, sürümlenmiş |
| API bir para akışına aracılık ediyor | İşlem değeri | Mutabakat kaydı ve iade/iptal karşılığı |
| Değer sonuçta, çağrıda değil (belge işleme) | Başarılı sonuç | Başarı tanımı ve itiraz akışı |
Dördüncü satır en zoru. "Başarılı sonuç" tanımını sözleşmeye yazmadan sonuç bazlı fiyatlandırma satmayın; ilk itirazda tanım tartışması açılır ve tahsilat durur.
Burası Kırılıyor: Sürümleme Politikası Olmayan API
Teknik olarak API'nizi sürümlemek kolay. Zor olan, eski sürümü ne zaman kapatacağınızı önceden söylemek ve sözünüzü tutmak.
Politikası olmayan ekiplerde şu olur: geriye uyumsuz bir değişiklik gerekir, kimse kapatma tarihi veremez, iki sürüm paralel yaşamaya başlar. Altı ay sonra üç sürüm olur. Her hata düzeltmesi üç yerde yapılır ve üçünün testi ayrı yazılır.
Yazılı politikanın üç bileşeni var: geriye uyumlu sayılan değişikliklerin listesi, bir sürümün destekleneceği asgari süre, ve kapatma öncesi bildirim penceresi. Bunlar geliştirici dokümanında yayımlanmadığı sürece hiçbiri gerçek değil.
Bir de sessiz kırılma var: yanıta yeni alan eklemek geriye uyumlu sayılır, ama katı şema doğrulaması yapan istemcilerde kırılır. Bunu politikanıza açıkça yazın ve istemci kütüphanelerinizde bilinmeyen alanları yok sayan bir ayrıştırma varsayılanı kullanın.
Türkiye Bağlamı: Bankacılıkta API Bir Ürün Değil, Yükümlülük
Türkiye'de finansal API açan ekipler için başlangıç noktası BDDK'nın "Bankaların Bilgi Sistemleri ve Elektronik Bankacılık Hizmetleri Hakkında Yönetmeliği"; 15 Mart 2020 tarihli ve 31069 sayılı Resmî Gazete'de yayımlandı, dayanağı 5411 sayılı Bankacılık Kanunu'nun 93'üncü maddesi ve 1 Temmuz 2020'de yürürlüğe girdi (bkz. RG 15.03.2020 / 31069).
Yönetmeliğin 3'üncü maddesi hem "açık bankacılık servisleri" hem de "API" için tanım veriyor. Bu, mühendislik açısından şu demek: bankayla entegre çalışan bir üründe API sözleşmenizin tarafı yalnızca banka değil, o bankanın tabi olduğu düzenleme. Arayüz tasarımını "banka ne verirse" diye bırakmak yerine, hangi servisin düzenlemede tanımlı olduğunu baştan okuyun.
Bu tarafın teknik ayrıntılarını, ödeme emri başlatma ve hesap bilgisi servislerini de içerecek şekilde banka entegrasyonu rehberimizde ele aldık. Kart tarafındaki akışlar için ödeme sistemi entegrasyonları sayfası daha uygun.
Efor Bandı
ininia'da yazılım geliştirme 300-400 USD/adam-gün bandında, adam-gün dökümüyle fiyatlanıyor. Dışa açılan bir API'nin ilk sürümü için teklifte ayrı satırlar hâlinde görmek isteyeceğiniz kalemler:
- Şema tasarımı, OpenAPI dosyası ve şemadan istemci üretimi
- Hata sözleşmesi: RFC 9457 gövdeleri,
typeURI kataloğu ve dokümantasyon sayfaları - Kimlik doğrulama ve istemci kayıt akışı (redirect URI yönetimi dahil)
- Kota sayacı, ağırlık tablosu ve kullanım raporlaması
- Sürümleme politikası, kullanımdan kaldırma başlıkları ve bildirim mekanizması
- Geliştirici portalı, anahtar yönetimi ve sandbox ortamı
Son iki kalem en çok hafife alınanlar. Sandbox'ı "üretimin kopyası" diye planlayan ekipler, veri tohumlama ve sıfırlama işini hiç bütçelemiyor. Kendi kapsamınız için bir bant görmek isterseniz proje fiyat hesaplama aracını kullanabilirsiniz.
Sırada Ne Var
Mevcut API'nizi açın ve tek bir test yapın: geçersiz bir istek gönderin, dönen gövdeye bakın. İçinde type, title, status ve detail var mı, type gerçek bir dokümantasyon sayfasına gidiyor mu? Gitmiyorsa, ilk iş budur ve bir günlük iştir.
İkinci iş, sürümleme politikasını yazıp yayımlamak. Kod değişikliği gerektirmiyor, ama onsuz hiçbir geriye uyumsuz değişikliği güvenle yapamazsınız. API tarafındaki çalışma biçimimizi API geliştirme sayfasında anlattık.
OpenAPI sürüm numarası ve sürümleme kuralı 25 Eylül 2026 tarihinde spec.openapis.org'dan; hata gövdesi üyeleri RFC 9457 metninden; OAuth 2.1 taslak numarası ve değişiklikleri IETF datatracker'dan; ödeme oranları Stripe'ın fiyatlandırma sayfasından; BDDK yönetmeliğinin tarih, sayı, dayanak ve yürürlük bilgileri Resmî Gazete metninden doğrulanmıştır. Fiyat bandı ininia'nın kendi tahmin modelindeki değerlerdir.
