> tpl_arc_012
API Mimarisi ve Geliştirici Deneyimi Standardı
REST (OpenAPI 3.1), gRPC ve GraphQL genelinde tasarım kalıplarını, URI taksonomisini, hata yanıt sözleşmelerini (RFC 7807), hız sınırlandırma başlıklarını, sürümleme ve kullanımdan kaldırma yaşam döngülerini ve otomatik denetim (linting) yönetişimini belirleyen kurumsal API mimari standardı ve geliştirici deneyimi (DevEx) kılavuzu.
Katı URI kurallarını, RFC 7807 hata formatlarını, uyumluluk kıran değişiklik politikalarını ve otomatik Spectral CI denetimini belirleyen kapsamlı API yönetişim kılavuzu.
Önemli Teknik Doküman Şablonu ve Hukuki Uyarı
TinyCTO.tv Teknik Doküman Şablon Bildirimi: Bu şablon genel eğitim ve operasyon amaçlı bir başlangıç materyalidir. Hukuki, vergisel, muhasebesel, yatırım, satın alma, mevzuat, güvenlik veya sertifikasyon danışmanlığı değildir. Gereklilikler ülkeye, kuruma, sözleşmeye ve riske göre değişir. Kullanmadan önce yetkin uzmanlarla gözden geçirip uyarlayın.
Çözülen Üretim Problemi
Farklı mühendislik ekipleri uyumsuz hata kodları, tutarsız isimlendirmeler ve öngörülemeyen kırıcı değişiklikler içeren standart dışı API'ler üretir; bu da önyüz istemcilerini ve entegrasyon ortaklarını bozar.
Ne Zaman Kullanılmalı?
- •Mikroservisler, mobil arka uçlar ve genel ortak API'leri için kurum genelinde API tasarım standartları belirlerken
- •CI/CD iş akışlarında sözleşme testlerini ve API stil denetimini (Spectral) otomatikleştirirken
- •API sürümlemeyi, kullanımdan kaldırma takvimlerini (Sunset başlıkları) ve geriye dönük uyumluluk garantilerini yönetirken
Ne Zaman Kullanılmamalı?
- •Kurum içi veritabanı varlık-ilişki şema tasarımında (TPL-ARC-008 kullanın)
- •Ağ güvenlik duvarı IP yönlendirme ve VPN yapılandırmasında (TPL-OPS-004 kullanın)
5 Şablon Bölümü ve Yapısal İskelet
Karar matrisi: Dış B2B ve mobil için REST (OpenAPI 3.1), yüksek performanslı iç servisler için gRPC (Protobuf), karmaşık önyüz toplama için GraphQL.
Kaynak isimlendirme (çoğul isimler, kebab-case), doğru HTTP fiilleri (GET, POST, PUT, PATCH, DELETE), idempotent işlemler ve imleçli (cursor) sayfalandırma.
Standart Problem Details formatı (type, title, status, detail, instance, invalid_params) ve tutarlı HTTP durum kodları (400, 401, 403, 404, 422, 429, 500).
OAuth2 kapsamları, JWT doğrulaması, servis ağı için mTLS, standart hız sınırlandırma başlıkları (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset).
URI sürümleme (/v1, /v2), kırıcı değişiklik tanımı, Sunset HTTP başlığı (RFC 8594), asgari 180 günlük kullanımdan kaldırma duyuruları ve Spectral CI.
Doldurma ve Uygulama Yönergeleri
Bağımsız İnceleme ve Onay Kontrol Listesi
- Tüm zorunlu bölümler dolduruldu
- Gizli anahtar veya parola içermiyor
- Yönetici sponsor onayı alındı
API Mimarisi ve Geliştirici Deneyimi Standardı - Örnek Vaka Analizi
Örnek Organizasyon: Sovereign Açık Bankacılık ve İş Ortağı API Mimari Standardı
Sovereign Açık Bankacılık ve İş Ortağı API Mimari Standardı için eksiksiz operasyonel uygulamayı gösteren gerçek dünya vaka analizi.
- •32 mühendislik ekibinde 240'tan fazla REST uç noktası birleşik OpenAPI 3.1 şartnamesi altında standartlaştırıldı
- •GitHub Actions'ta otomatik Spectral denetimi kurularak standart dışı API şeması içeren PR'lar birleşme öncesi tamamen engellendi
- •İç servisler arası RPC iletişiminin REST'ten gRPC'ye geçirilmesiyle p99 gecikme süresi 45 ms'den 6 ms'ye düşürüldü
Sıkça Sorulan Sorular
Kurumsal API'ler neden RFC 7807 (Problem Details) standardını benimsemelidir?
Standart olmadığında her ekip kendi hata JSON yapısını üretir (örn. {"error": "..."}, {"message": "..."}). RFC 7807, makine tarafından okunabilir alanlara (type URI, title, status, detail, invalid_params) sahip IETF standardı bir format sunarak istemci SDK'larının doğrulama ve yetkilendirme hatalarını tek tip yönetmesini sağlar.
"Sunset" HTTP başlığı (RFC 8594) nedir ve API kullanımdan kaldırma sürecini nasıl yönetir?
Sunset başlığı, bir uç noktanın veya sürümün gelecekteki belirli bir tarihten sonra yanıt vermeyeceğini HTTP yanıt başlıklarında duyurur (örn. "Sunset: Wed, 11 Nov 2026 00:00:00 GMT"). Deprecation başlığıyla birlikte kullanıldığında istemci geliştiricilerine programatik ve otomatik erken uyarı sağlar.
Kurumsal API'lerde imleç tabanlı (cursor) sayfalandırma neden offset tabanlıya göre üstündür?
Offset tabanlı sayfalandırma ("OFFSET 10000 LIMIT 50"), veritabanının binlerce satırı tarayıp atmasını gerektirir; bu da büyük tablolarda aşırı gecikmeye ve CPU yüküne yol açar. Ayrıca sayfalama sırasında yeni kayıt eklendiğinde mükerrer veya kayıp kayıtlar oluşur. İmleç tabanlı sayfalandırma ("WHERE id > cursor LIMIT 50") ise sabit O(1) indeks erişimi sağlar.
Teknik Doküman Şablon Paketi
Giriş GerekliTüm boş şablonları, işlenmiş senaryoları ve doğrulama manifestolarını tek bir arşivde indirin.
Yetkili Standartlar ve Kaynaklar
- RFC 7807 Problem Details for HTTP APIsIETF • OFFICIAL REQUIREMENT
- OpenAPI Specification 3.1.0OpenAPI Initiative • OFFICIAL REQUIREMENT