API Dokümantasyonunda Swagger Kullanımı ve Standardizasyon

Bir API teknik olarak kusursuz çalışabilir, fakat onu kullanacak ekip nereden başlayacağını bilmiyorsa entegrasyon yine yavaşlar. On yılı aşan backend ve API geliştirme pratiğinde en sık gördüğüm sorun, dokümantasyonun kod tamamlandıktan sonra hazırlanması ve kısa sürede gerçek sistemden kopmasıdır. API Dokümantasyonunda Swagger Kullanımı ve Standardizasyon yaklaşımı tam olarak bu sorunu çözmeyi hedefler. Swagger ile API dokümantasyonu nasıl hazırlanır, OpenAPI Specification ile REST API dokümantasyonu nasıl standardize edilir ve bu sözleşme geliştirme sürecinin aktif parçası haline nasıl getirilir sorularını birlikte ele alacağız. Rehberin sonunda Swagger UI Swagger Editor ve OpenAPI araçları nasıl kullanılır sorusundan kurumsal API governance süreçlerine kadar uygulanabilir bir çerçeveye sahip olacaksınız.

API Dokümantasyonu Nedir?

API dokümantasyonu, bir servisin hangi kaynakları sunduğunu ve bu kaynaklarla nasıl iletişim kurulacağını anlatan teknik bilgi bütünüdür. Sadece endpoint listesinden oluşmaz. Parametreleri, veri modellerini, kimlik doğrulamayı, hata davranışlarını ve kullanım senaryolarını da kapsar. İyi hazırlanmış bir doküman hem insan tarafından okunabilir hem de mümkün olduğunda araçlar tarafından işlenebilir olmalıdır. OpenAPI bu noktada dokümantasyonu yürütülebilir bir sözleşmeye yaklaştırır.

API Dokümantasyonunun Amacı

Temel amaç geliştiricinin API'yi tahmin ederek kullanmak zorunda kalmamasıdır. Bir isteğin nereye gönderileceği açık olmalıdır. Hangi alanların zorunlu olduğu anlaşılmalıdır. Başarılı ve başarısız cevaplar önceden bilinmelidir. Böylece entegrasyon deneme yanılma sürecinden çıkar ve öngörülebilir hale gelir.

API Reference ile Developer Guide Arasındaki Fark

API Reference teknik sözleşmenin ayrıntılı görünümüdür. Endpoint, parameter, schema ve response gibi bilgiler burada bulunur. Developer Guide ise kullanım senaryosunu ve iş akışını açıklar. Bir ödeme sürecinin hangi sırayla yürütüleceğini reference tek başına anlatmayabilir. Bu nedenle güçlü dokümantasyon her iki yaklaşımı birlikte kullanır.

İyi API Dokümantasyonu Neden Önemlidir?

Dokümantasyon kalitesi doğrudan geliştirici deneyimini etkiler. Eksik bilgi daha fazla soru oluşturur. Tutarsız örnekler yanlış entegrasyona yol açar. Güncel bir sözleşme ise ekiplerin daha bağımsız çalışmasını sağlar. Özellikle kurumsal sistemlerde dokümantasyon operasyonel verimliliğin önemli parçalarından biridir.

Developer Experience

Developer Experience, API tüketicisinin ilk karşılaşmadan çalışan entegrasyona ulaşmasına kadar yaşadığı deneyimdir. Açık isimler bu süreci kolaylaştırır. Gerçekçi örnekler öğrenme süresini düşürür. Tutarlı hata cevapları sorun çözmeyi hızlandırır. İyi dokümantasyon burada doğrudan ürün kalitesine dönüşür.

Entegrasyon Süresi

Entegrasyon süresi yalnızca kod yazma süresi değildir. Doküman arama ve soru sorma zamanı da buna dahildir. Belirsiz authentication akışı günler kaybettirebilir. Çalışan örnekler bu süreyi ciddi biçimde azaltır. Hedef, ilk başarılı çağrıya mümkün olduğunca erken ulaşmaktır.

Destek Talebi Sayısı

Tekrarlayan destek soruları çoğu zaman dokümantasyon açığını gösterir. Aynı endpoint hakkında sürekli soru geliyorsa açıklama yetersiz olabilir. Destek kayıtları bu nedenle değerli geri bildirim kaynaklarıdır. Sık sorulan konular dokümana eklenmelidir. Böylece ekip zamanını daha zor teknik problemlere ayırabilir.

API Benimsenmesi

Kolay öğrenilen API daha hızlı benimsenir. Kullanıcı ilk denemede başarılı sonuç gördüğünde güven artar. Karmaşık başlangıç süreci ise tüketiciyi uzaklaştırabilir. Dokümantasyon bu nedenle yalnızca teknik bir çıktı değildir. API ürününün kullanılabilirliğini de doğrudan etkiler.

API Dokümantasyonu Kimler İçin Yazılır?

Doküman yalnızca backend geliştiriciyi hedeflememelidir. Frontend, mobil, test ve partner ekiplerinin beklentileri farklıdır. Her grubun aynı sözleşmeden yararlanması önemlidir. Ancak kullanım örnekleri hedef kitlenin ihtiyacına göre çeşitlenebilir. Başarılı dokümantasyon bu farklı tüketici profillerini birlikte düşünür.

Backend Geliştiriciler

Backend geliştirici veri modeline ve davranış sözleşmesine odaklanır. Status code seçimi onun için önemlidir. Idempotency ve rate limiting ayrıntılarını bilmek ister. Schema değişikliklerini erken görmek ister. OpenAPI bu bilgileri ortak formatta sunabilir.

Frontend Geliştiriciler

Frontend ekibi request ve response yapısını hızlı görmek ister. Optional alanların açık olması önemlidir. Enum değerleri arayüz davranışını etkiler. Mock response desteği geliştirmeyi hızlandırır. İyi bir OpenAPI sözleşmesi frontend ekibinin backend'i beklemeden ilerlemesini sağlar.

Mobile Geliştiriciler

Mobil geliştiriciler geriye uyumluluğa özellikle dikkat eder. Uygulamalar her zaman aynı anda güncellenmez. Response alanının aniden kaldırılması eski sürümleri bozabilir. Versioning ve deprecation bilgileri bu yüzden kritiktir. Dokümantasyon mobil yaşam döngüsünü hesaba katmalıdır.

Partner Entegrasyon Ekipleri

Partner ekipler kurum içi bilgileri bilmez. Bu nedenle doküman daha açıklayıcı olmalıdır. Authentication süreci adım adım gösterilmelidir. Rate limit ve hata davranışları açıkça belirtilmelidir. Dış tüketici açısından belirsiz bırakılan her alan destek yükünü artırır.

QA ve Test Ekipleri

QA ekipleri sözleşmeyi test senaryolarına dönüştürür. Required alanlar doğrudan negatif test üretmeye yardımcı olur. Status code tanımları beklenen davranışı belirler. Example veriler test hazırlığını hızlandırır. Contract testing yaklaşımı bu ilişkinin otomatik hale gelmesini sağlayabilir.

Swagger Nedir?

Swagger adı API dünyasında hem tarihsel bir specification hem de araç ailesi nedeniyle kullanılır. Bugün teknik ayrımı doğru yapmak önemlidir. API sözleşmesini tanımlayan standart OpenAPI Specification'dır. Swagger adı ise Swagger UI, Swagger Editor ve benzeri araçlarla ilişkilidir. Bu ayrımı bilmek kurumsal dokümantasyonda kullanılan terminolojiyi daha anlaşılır hale getirir.

Swagger'ın Tarihçesi

Swagger başlangıçta REST API'lerini tarif etmek için geliştirilen bir specification olarak ortaya çıktı. Zamanla geniş bir geliştirici topluluğu tarafından kullanılmaya başlandı. Specification daha sonra OpenAPI Initiative çatısı altında OpenAPI adıyla devam etti. Swagger markası araç ekosisteminde yaşamaya devam etti. Bugünkü terminolojinin kaynağı bu tarihsel geçiştir.

Swagger Specification Nedir?

Swagger Specification, OpenAPI adlandırmasından önce kullanılan API tanımlama formatıdır. Endpoint ve veri modellerini makine tarafından işlenebilir biçimde tanımlar. Swagger 2.0 bu dönemin yaygın sürümüdür. Yeni projelerde genellikle OpenAPI 3.x ailesi tercih edilir. Eski sistemlerde Swagger 2.0 dosyalarıyla karşılaşmak hâlâ mümkündür.

Swagger 2.0 Nedir?

Swagger 2.0 eski fakat yaygın bir API tanımlama sürümüdür. Dosyanın başında genellikle swagger değeri bulunur. Request body ve reusable object yapıları yeni OpenAPI sürümlerinden farklı modellenir. Modern ihtiyaçlarda OpenAPI 3.x daha geniş yetenek sunar. Legacy API'lerde geçiş planı hazırlanırken mevcut tooling desteği kontrol edilmelidir.

Swagger ile OpenAPI Arasındaki İlişki

OpenAPI bugün specification tarafını temsil eder. Swagger ise bu specification etrafında kullanılan araç isimlerinde yaşamaktadır. Swagger UI OpenAPI belgesini görselleştirebilir. Swagger Editor belgenin hazırlanmasına yardımcı olabilir. Bu nedenle iki kavram bağlantılıdır fakat teknik olarak aynı şeyi ifade etmez.

Swagger Günümüzde Bir Standart mı Yoksa Araç Seti mi?

Güncel kullanımda standart olarak OpenAPI Specification demek daha doğrudur. Swagger adı ağırlıklı olarak tooling tarafında kullanılır. Ekip içi terminolojide bu ayrım netleştirilmelidir. Böylece specification sürümü ile kullanılan aracı birbirine karıştırma riski azalır. Kurumsal belgelerde OpenAPI sürümünün açıkça belirtilmesini öneriyorum.

OpenAPI Specification Nedir?

OpenAPI Specification, HTTP tabanlı API'lerin yapısını ortak bir söz dizimiyle tanımlayan açık bir standarttır. Paths, operations, parameters, request body, responses ve security gibi alanları tarif eder. Belge YAML veya JSON olarak tutulabilir. En önemli faydası dokümanı makine tarafından işlenebilir bir API contract haline getirmesidir. Böylece aynı dosya dokümantasyon, test, SDK ve governance süreçlerinde kullanılabilir.

OpenAPI Ne İşe Yarar?

OpenAPI API davranışının ortak dilini oluşturur. İnsanlar belgeyi okuyabilir. Araçlar aynı belgeyi parse edebilir. CI süreçleri kuralları otomatik kontrol edebilir. Bu ortak format ekipler arasındaki sözlü anlaşmalara duyulan ihtiyacı azaltır.

Machine-Readable API Contract Nedir?

Machine-readable contract, API sözleşmesinin yazılımlar tarafından okunabilir olmasıdır. Endpoint adı yalnızca açıklama metninde kalmaz. Veri tipi yapılandırılmış biçimde belirtilir. Required alanlar doğrudan işlenebilir. Böylece otomasyon sistemleri sözleşmeyi test ve kod üretimi için kullanabilir.

OpenAPI ile Neler Yapılabilir?

OpenAPI yalnızca referans sayfası üretmek için kullanılmamalıdır. Aynı sözleşme farklı mühendislik süreçlerinin girdisi olabilir. Bu yaklaşım bilgi tekrarını azaltır. Spec tek kaynak haline geldikçe ekipler arasında tutarlılık artar. Benim tercih ettiğim model de OpenAPI dosyasını geliştirme zincirinin aktif bileşeni yapmaktır.

Dokümantasyon Üretimi

OpenAPI'den otomatik API reference üretilebilir. Endpoint listeleri elle yazılmak zorunda kalmaz. Schema değişiklikleri dokümana yansıtılabilir. Swagger UI bunun bilinen örneklerinden biridir. Yine de kavramsal rehberler ayrıca hazırlanmalıdır.

SDK Üretimi

Spec istemci kodu üretiminde kullanılabilir. operationId burada kritik rol oynar. Schema isimleri SDK ergonomisini etkiler. Tutarlı isimlendirme daha okunabilir metotlar üretir. Generated SDK yine entegrasyon testlerinden geçirilmelidir.

Server Stub Üretimi

OpenAPI sunucu tarafı başlangıç kodu üretiminde kullanılabilir. Bu yaklaşım özellikle design-first ekiplerde faydalıdır. Endpoint imzaları sözleşmeden oluşturulur. Uygulama mantığı ekip tarafından tamamlanır. Böylece contract ile implementasyon arasında başlangıç uyumu sağlanır.

Mock Server

Mock server gerçek backend tamamlanmadan örnek cevap döndürebilir. Frontend bu servisle geliştirmeye başlayabilir. Partner ekipler entegrasyon akışını erkenden deneyebilir. Example verilerin kalitesi burada doğrudan sonucu etkiler. Gerçekçi örnekler daha faydalı mock davranışı sağlar.

API Testing

OpenAPI test üretimine veri sağlayabilir. Parametre kuralları otomatik kontrol edilebilir. Response schema doğrulanabilir. Beklenmeyen status code tespit edilebilir. Bu sayede test kapsamı sözleşmeyle ilişkilendirilebilir.

Contract Testing

Contract testing gerçek API davranışını spec ile karşılaştırır. Response tipleri kontrol edilir. Required alanlar doğrulanır. Status code uyumu ölçülür. Spec drift erken aşamada yakalanabilir.

Governance

Governance kurumsal standartların tüm API'lerde uygulanmasını hedefler. Naming kuralları otomatik denetlenebilir. Security tanımları zorunlu hale getirilebilir. Breaking change kontrolleri pipeline'a eklenebilir. OpenAPI böylece yönetişim için ölçülebilir bir temel oluşturur.

Swagger ve OpenAPI Arasındaki Fark Nedir?

En kolay açıklama şudur: OpenAPI specification'dır, Swagger ise bu specification çevresinde kullanılan araçların önemli bir bölümünü temsil eder. Bu fark özellikle ekip içi konuşmalarda önemlidir. Bir geliştirici “Swagger sürümünü yükseltiyoruz” dediğinde hangi parçadan söz edildiği belirsiz kalabilir. OpenAPI sürümü ile Swagger UI sürümü birbirinden bağımsız kavramlardır. Teknik dokümanda her birini açık isimle belirtmek daha sağlıklı sonuç verir.

OpenAPI = Specification

OpenAPI API sözleşmesinin formatını tanımlar. Paths gibi temel nesneleri tarif eder. Sürümleri bağımsız olarak yayımlanır. Araçlardan bağımsızdır. Aynı OpenAPI dosyası farklı yazılımlar tarafından kullanılabilir.

Swagger = Tooling Ecosystem

Swagger adı çeşitli geliştirme araçlarında kullanılır. Bunların her birinin görevi farklıdır. UI görselleştirmeye odaklanır. Editor yazım ve kontrol deneyimi sunar. Bu nedenle Swagger ifadesini tek başına specification yerine kullanmak teknik belirsizlik oluşturabilir.

Swagger UI

Swagger UI OpenAPI belgesini etkileşimli bir web arayüzünde gösterir. Endpoint'ler gruplanabilir. Schema bilgileri görüntülenebilir. Uygun yapılandırmada istek gönderilebilir. Özellikle API reference katmanında oldukça kullanışlıdır.

Swagger Editor

Swagger Editor OpenAPI belgesini düzenlemeyi kolaylaştırır. Yazım sırasında syntax geri bildirimi sağlar. Tanımın görsel çıktısını aynı anda gösterebilir. Design-first yaklaşımda hızlı review yapılmasına yardımcı olur. Spec yazmayı düz metin düzenleyiciden daha erişilebilir hale getirebilir.

Swagger Codegen

Swagger Codegen API tanımından istemci veya sunucu kodu üretmek için kullanılabilir. Üretilen kodun kalitesi spec kalitesine bağlıdır. Kötü operationId isimleri kötü metot isimleri üretir. Belirsiz schema yapıları SDK kullanımını zorlaştırır. Bu nedenle code generation standardizasyonun yerine geçmez.

Swagger Studio / Kurumsal Tasarım Araçları

Kurumsal tasarım araçları ekiplerin birlikte API sözleşmesi hazırlamasını kolaylaştırabilir. Review süreci merkezi hale getirilebilir. Erişim kontrolü uygulanabilir. Ortak tasarım kuralları ekipler arasında paylaşılabilir. Ancak temel sözleşmenin açık OpenAPI standardında tutulması taşınabilirlik açısından değerlidir.

“Swagger Dokümanı” Demek Teknik Olarak Doğru mu?

Günlük konuşmada bu ifade anlaşılır olabilir. Teknik belgede OpenAPI dokümanı demek daha nettir. Swagger UI tarafından gösterilen dosya aslında OpenAPI specification olabilir. Özellikle yeni ekip üyeleri için kavramları doğru ayırmak faydalıdır. Ben kurumsal style guide içinde terminoloji standardı da tanımlanmasını öneriyorum.

OpenAPI Sürümleri

OpenAPI sürüm seçimi yalnızca yeni özelliklere bakılarak yapılmamalıdır. Kullanılan framework, code generator, linter ve gateway desteği birlikte değerlendirilmelidir. OpenAPI 3.0 uzun süre geniş tooling desteğine sahip olduğu için çok sayıda projede kullanılmaktadır. OpenAPI 3.1 JSON Schema ile uyum tarafında önemli gelişmeler getirir. OpenAPI 3.2 ise yeni projelerde değerlendirilmesi gereken güncel specification ailesinin devamıdır, fakat tüm araç zincirinin uyumluluğu kontrol edilmelidir.

Swagger / OpenAPI 2.0

2.0 eski projelerde hâlâ görülebilir. Request body modelleme şekli 3.x sürümlerinden farklıdır. Components yerine definitions gibi yapılar kullanılır. Migration yaparken yalnızca sürüm satırını değiştirmek yeterli değildir. Semantik değişiklikler araçlarla ve testlerle doğrulanmalıdır.

OpenAPI 3.0

OpenAPI 3.0 geniş kullanım alanına ulaşmış bir sürüm ailesidir. Components yapısı tekrar kullanılabilir tanımları düzenler. Request body ayrı bir nesne olarak modellenir. Multiple servers gibi özellikler daha açık biçimde ifade edilir. Tooling uyumluluğu güçlü olduğu için mevcut sistemlerde sık görülür.

OpenAPI 3.1

OpenAPI 3.1 schema modelinde JSON Schema ile daha yakın uyum sağlar. Null değerlerin modellenmesi değişir. Webhooks gibi yetenekler specification içinde daha doğal ele alınır. Schema tasarımında kullanılan araçların 3.1 desteği kontrol edilmelidir. Özellikle eski code generator sürümleriyle uyumluluk test edilmelidir.

OpenAPI 3.2

OpenAPI 3.2 güncel specification sürüm ailesinin bir parçasıdır. Yeni projede değerlendirilmesi mantıklıdır. Ancak yalnızca specification desteğinin yayımlanmış olması yeterli değildir. Swagger UI, generator, linter ve gateway zincirinin gerçek desteği ayrıca doğrulanmalıdır. Üretim kararını tooling matrisi üzerinden vermek daha güvenlidir.

OpenAPI 3.0, 3.1 ve 3.2 Arasındaki Farklar

3.0 en yaygın eski 3.x tabanlarından biridir. 3.1 JSON Schema uyumunu önemli ölçüde geliştirir. 3.2 standardın sonraki geliştirmelerini taşır. Her yükseltmede schema davranışı ve araç desteği birlikte incelenmelidir. Sürüm seçimi yalnızca yenilik isteğine göre yapılmamalıdır.

Yeni Projede Hangi OpenAPI Sürümü Kullanılmalı?

Yeni projede öncelikle hedef tooling listesi çıkarılmalıdır. Ardından bu araçların desteklediği en güncel ortak sürüm belirlenmelidir. Tüm zincir 3.2 ile güvenilir çalışıyorsa güncel sürüm tercih edilebilir. Uyumsuz kritik bir araç varsa 3.1 geçici olarak daha güvenli olabilir. Karar belgelenmeli ve yükseltme planı tutulmalıdır.

Tooling Uyumluluğu Neden Kontrol Edilmelidir?

Specification desteği araçlar arasında aynı hızda ilerlemez. Editor dosyayı kabul ederken generator farklı davranabilir. Gateway bazı özellikleri yok sayabilir. CI validator farklı hata üretebilir. Bu nedenle sürüm kararı gerçek pipeline üzerinde test edilmelidir.

OpenAPI Dosyası YAML mı JSON mu Olmalı?

YAML ve JSON aynı OpenAPI modelini ifade edebilir. Dosya formatı API'nin gerçek HTTP davranışını değiştirmez. İnsan tarafından yoğun biçimde düzenlenen spec'lerde YAML genellikle daha okunabilir bulunur. Otomatik üretilen dosyalarda JSON doğal bir çıktı olabilir. Kurumsal standart açısından asıl önemli konu format seçiminin ekip genelinde tutarlı olmasıdır.

YAML Avantajları

YAML daha az noktalama işareti içerir. Büyük dosyalarda okunması kolay olabilir. Code review sırasında değişiklikler daha rahat görülebilir. Elle yazılan spec'lerde tercih edilir. Girinti hatalarına karşı linter kullanılması faydalıdır.

JSON Avantajları

JSON pek çok araç tarafından doğal biçimde üretilir. Parser desteği çok yaygındır. Yapısı kesin sınırlar taşır. Otomatik süreçlerde güvenilir biçimde işlenebilir. İnsan tarafından büyük dosyalarda düzenlenmesi daha yorucu olabilir.

İnsan Tarafından Düzenlenen Spec İçin YAML

Design-first ekiplerde YAML pratik bir tercihtir. Pull request diff'leri daha okunabilir olur. Açıklamalar rahatça düzenlenebilir. Ortak style kuralları uygulanmalıdır. Formatter kullanmak biçim farklarını azaltır.

Otomatik Üretilen Spec İçin JSON

Code-first sistemlerde framework JSON üretebilir. Bu durum tamamen normaldir. Canonical dosyanın JSON olması teknik sorun oluşturmaz. Yine de version control'e alınacak çıktı deterministik olmalıdır. Gereksiz sıralama değişiklikleri diff kalitesini düşürmemelidir.

YAML ve JSON Arasında Dönüşüm

İki format arasında araçlarla dönüşüm yapılabilir. Dönüşüm sonrasında semantic validation çalıştırılmalıdır. Reference yollarının korunduğu kontrol edilmelidir. Büyük spec'lerde otomatik test kullanmak faydalıdır. Format dönüşümünün contract değişikliği yaratmaması beklenir.

Dosya Formatının API Davranışını Değiştirmemesi

YAML veya JSON seçimi HTTP endpoint davranışını belirlemez. Aynı model iki formatta da temsil edilebilir. Fark geliştirici deneyimi ve tooling tarafındadır. Kurumsal karar bu kriterlere göre verilmelidir. API tasarım kuralları format seçiminin önünde tutulmalıdır.

OpenAPI Dokümanının Temel Yapısı

Sağlıklı bir OpenAPI dosyası yalnızca paths bölümünden oluşmaz. Metadata, servers, reusable components ve security gibi alanlar bütünün parçasıdır. Bu yapı standart hale geldiğinde farklı API'leri okumak kolaylaşır. Yeni ekip üyesi dosyada hangi bilgiyi nerede bulacağını tahmin edebilir. Kurumsal API dokümantasyonunda endpoint schema authentication ve versioning standartları bu ana yapının üzerine kurulmalıdır.

openapi

openapi alanı kullanılan specification sürümünü belirtir. API ürün sürümü değildir. Tooling bu değere göre belgeyi yorumlar. Yanlış sürüm değeri beklenmeyen validation sonuçları yaratabilir. Bu alan bilinçli biçimde güncellenmelidir.

info

info API hakkında temel metadata taşır. Başlık ve sürüm burada bulunur. Açıklama ve iletişim bilgileri de eklenebilir. API sahibini bulmak için iyi bir başlangıç noktasıdır. Kurumsal standartta bu alanın eksiksiz olması gerekir.

servers

servers API'nin erişilebilir olduğu temel adresleri tanımlar. Development ve production ortamları ayrılabilir. Değişkenler kullanılabilir. Public olmayan adreslerin yayımlanmasına dikkat edilmelidir. Ortam bilgisi güvenlik politikasıyla birlikte düşünülmelidir.

paths

paths API'nin endpoint haritasını taşır. URI ve HTTP operation bilgileri burada yer alır. Parametreler ve response'lar operation düzeyinde tanımlanır. Tasarım standardının büyük bölümü bu alanda görünür hale gelir. Lint kuralları paths üzerinde yoğun biçimde kullanılabilir.

components

components tekrar kullanılabilir tanımları merkezi hale getirir. Schema ve response burada tutulabilir. Security scheme tanımları da bu bölümde yer alır. Tekrarı azaltmak bakım maliyetini düşürür. Kurumsal component library yaklaşımı bu yapıyı daha da güçlendirir.

security

security API'nin kimlik doğrulama gereksinimlerini belirtir. Global olarak tanımlanabilir. Operation seviyesinde değiştirilebilir. Public endpoint'ler ayrıca modellenebilir. Gerçek credential hiçbir zaman spec içine yazılmamalıdır.

tags

tags endpoint'leri anlamlı gruplara ayırır. Swagger UI gibi arayüzlerde gezinmeyi kolaylaştırır. Resource veya domain bazlı kullanılabilir. Fazla sayıda tag bilgi mimarisini bozabilir. Kurum genelinde tag standardı belirlemek faydalıdır.

externalDocs

externalDocs daha kapsamlı rehberlere yönlendirme sağlayabilir. API reference içinde anlatılması uygun olmayan içerikler buraya bağlanabilir. Authentication guide buna örnektir. Migration rehberi de bağlantılanabilir. Linklerin güncelliği düzenli kontrol edilmelidir.

webhooks

webhooks API'nin dış sisteme yaptığı callback davranışlarını tanımlamaya yardımcı olur. Event payload açık biçimde belgelenebilir. Güvenlik doğrulaması açıklanmalıdır. Retry davranışı ayrıca yazılmalıdır. Tüketicinin gelen isteği nasıl işleyeceği net olmalıdır.

info Bölümü Nasıl Standardize Edilmeli?

info alanı küçük görünse de API'nin kimliğini tanımlar. Kurumsal ölçekte onlarca servis olduğunda başlık, sahip ve sürüm bilgisinin ortak formatta tutulması ciddi kolaylık sağlar. Ben API owner ve support kanalının dokümanın ilk ekranından bulunabilmesini özellikle değerli görüyorum. Bir problem çıktığında doğru ekibe ulaşmak için repository aramak gerekmemelidir. info alanı bu operasyonel ihtiyacı karşılayacak şekilde standardize edilmelidir.

title

title API'yi açık şekilde tanımlamalıdır. Genel ifadelerden kaçınılmalıdır. Servis veya domain adı anlaşılmalıdır. Ortam bilgisi başlığa karıştırılmamalıdır. Naming convention kurum genelinde aynı olmalıdır.

summary

summary kısa değer açıklaması sunar. API'nin ne yaptığını tek bakışta anlatmalıdır. Pazarlama cümlesinden çok teknik özet olmalıdır. Gereksiz ayrıntıya girilmemelidir. Ayrıntılar description içinde verilmelidir.

description

description API'nin kapsamını açıklar. Temel davranış ve önemli kısıtlar belirtilir. Gerekirse ek rehber bağlantıları eklenir. Endpoint ayrıntıları burada tekrar edilmemelidir. Okuyucu API'nin sınırlarını anlayabilmelidir.

version

version API ürün sürümünü temsil eder. OpenAPI specification sürümüyle karıştırılmamalıdır. Release politikasına göre güncellenmelidir. Semantic versioning kullanılıyorsa anlamı style guide içinde açıklanmalıdır. Changelog ile ilişkilendirilmesi faydalıdır.

contact

contact destek veya sahiplik bilgisini sunar. Aktif bir kanal kullanılmalıdır. Ayrılan çalışanların kişisel adreslerine bağlı kalınmamalıdır. Takım bazlı iletişim daha dayanıklıdır. Bilginin güncelliği otomatik kontrol edilebilir.

license

Public API veya açık spec'lerde license bilgisi gerekli olabilir. Lisans seçimi kurum politikasıyla uyumlu olmalıdır. Rastgele değer kullanılmamalıdır. Hukuki ekip gereksinimleri dikkate alınmalıdır. Internal API'lerde kullanım şekli ayrıca tanımlanabilir.

API Owner Bilgisi

Her API'nin belirli bir sahibi olmalıdır. Sahip ekip teknik kararların sorumluluğunu taşır. Catalog içinde aynı bilgi görünmelidir. x-owner gibi extension alanları kullanılabilir. Ownership değişiklikleri otomatik süreçle güncellenmelidir.

Support Kanalı

Support kanalı tüketicinin yardım isteyebileceği yeri gösterir. Kanalın aktif olması önemlidir. Internal ekiplerde ortak destek grubu kullanılabilir. Public API'lerde uygun destek sayfası tercih edilebilir. Kullanılmayan iletişim adresleri dokümantasyon kalitesini düşürür.

servers Bölümü Nasıl Kullanılır?

servers alanı yalnızca base URL yazılan bir bölüm olarak görülmemelidir. Ortamların doğru ayrılması geliştiricinin yanlış sisteme istek göndermesini önler. Production adresi ile staging adresinin açık biçimde ayrılması özellikle Try It Out kullanılan ortamlarda önemlidir. Internal host bilgileri public specification içine taşınmamalıdır. Server politikası güvenlik ve deployment modeliyle birlikte belirlenmelidir.

Development Server

Development server yerel veya geliştirme ortamını gösterir. Gerçek müşteri verisi içermemelidir. Geliştirici testleri için kullanılabilir. URL açıkça etiketlenmelidir. Public spec'te gereksiz internal adres yayımlanmamalıdır.

Staging Server

Staging production'a yakın davranış sunmalıdır. Entegrasyon testleri burada çalıştırılabilir. Swagger UI Try It Out için iyi bir hedef olabilir. Credential politikası production'dan ayrılmalıdır. Test verileri güvenli tutulmalıdır.

Production Server

Production URL gerçek tüketicilerin kullandığı adrestir. Yanlışlıkla yazma operasyonu çalıştırma riski düşünülmelidir. Swagger UI erişimi buna göre yapılandırılmalıdır. Public API'lerde adresin dokümante edilmesi gerekir. Internal endpoint ayrımı korunmalıdır.

Server Variables

Server variables tekrar eden URL yapılarını esnek hale getirir. Region veya tenant gibi değişkenler modellenebilir. Default değer anlamlı olmalıdır. Kabul edilen değerler sınırlandırılabilir. Fazla değişken kullanımı dokümanı anlaşılmaz hale getirmemelidir.

Internal ve External Server Ayrımı

Internal ve external endpoint'ler aynı güvenlik seviyesinde değildir. Public dokümanda internal hostname yayımlanmamalıdır. Gerekirse ayrı specification üretilmelidir. Build sırasında filtreleme uygulanabilir. Bu ayrım bilgi sızıntısı riskini azaltır.

Production URL'lerini Dokümante Etme

Production adresi tüketici açısından açık olmalıdır. Protokol doğru yazılmalıdır. Versiyon path içinde bulunuyorsa tutarlı gösterilmelidir. Alternatif region adresleri belgelenebilir. Kullanılmayan eski hostlar dokümandan kaldırılmalıdır.

paths ve Operations Nasıl Tanımlanır?

paths ve operations API davranışının en görünür bölümüdür. Her operation tek bir kullanım amacını açık biçimde anlatmalıdır. HTTP method seçimi resource davranışıyla uyumlu olmalıdır. Summary, description, security, parameters ve responses birlikte düşünülmelidir. İyi tasarlanmış operation geliştiriciye yalnızca teknik adresi değil, beklenen davranışı da gösterir.

GET

GET veri okumak için kullanılmalıdır. Normal koşullarda sunucu durumunu değiştirmemelidir. Liste ve detay endpoint'lerinde sık görülür. Cache davranışı gerekiyorsa açıklanmalıdır. Response schema açık biçimde tanımlanmalıdır.

POST

POST genellikle yeni işlem veya resource oluşturur. Request body ayrıntılı tanımlanmalıdır. Tekrar gönderim davranışı açıklanmalıdır. Idempotency gerekiyorsa header standardı eklenmelidir. Başarılı oluşturma için uygun status code kullanılmalıdır.

PUT

PUT çoğunlukla belirli resource'un güncellenmesini temsil eder. Idempotent davranış beklenir. Full replacement veya update semantiği açık olmalıdır. Required alanlar buna göre belirlenmelidir. Aynı kurumda farklı anlamlarla kullanılmamalıdır.

PATCH

PATCH kısmi güncelleme için kullanılabilir. Hangi alanların değiştirilebilir olduğu belirtilmelidir. Null gönderimin anlamı açık olmalıdır. Validation kuralları açıklanmalıdır. Response davranışı diğer update endpoint'leriyle tutarlı olmalıdır.

DELETE

DELETE resource silme işlemini temsil eder. Soft delete kullanılıyorsa açıklanmalıdır. Tekrar çağrının sonucu belirlenmelidir. Response body olup olmadığı standardize edilmelidir. Yetki gereksinimi açıkça gösterilmelidir.

OPTIONS

OPTIONS desteklenen iletişim seçeneklerini göstermek için kullanılabilir. Browser CORS süreçlerinde görülebilir. Uygulama davranışı net olmalıdır. Gereksiz operation olarak belgelenmemelidir. Gateway tarafından otomatik yönetiliyorsa bu durum ayrıca değerlendirilmelidir.

HEAD

HEAD response body olmadan metadata almak için kullanılabilir. GET ile ilişkilidir. Header davranışı belgelenmelidir. Kullanılmıyorsa sırf eksiksiz görünmek için eklenmemelidir. Gerçek implementasyonla spec aynı olmalıdır.

Operation Summary

Summary kısa ve eylem odaklı olmalıdır. Endpoint'in amacını hemen anlatmalıdır. Aynı tag altındaki summary'ler benzer kalıpta yazılabilir. Gereksiz teknik ayrıntı eklenmemelidir. Ayrıntılar description alanında tutulmalıdır.

Operation Description

Description davranışın önemli ayrıntılarını açıklar. Yetki kısıtları belirtilebilir. İş kuralları özetlenebilir. Edge case bilgileri eklenebilir. Tutorial yerine geçecek kadar uzun tutulmamalıdır.

API Endpoint İsimlendirme Standardı

Endpoint isimlendirmesi API'nin öğrenilebilirliğini doğrudan etkiler. Bir endpoint'in nasıl adlandırılacağını her ekip ayrı kararlaştırırsa tüketici her serviste yeni bir dil öğrenir. Resource-oriented yaklaşım bu sorunu azaltır. URI'lerde mümkün olduğunca isim tabanlı ve tutarlı bir yapı kullanmak okunabilirliği artırır. Standardın yazılı hale getirilmesi ve lint edilebilen bölümlerinin otomatik kontrol edilmesi gerekir.

Resource-Oriented API Design

Resource-oriented tasarım iş varlıklarını merkez alır. users ve orders buna örnektir. HTTP method davranışı ifade eder. URI resource'u gösterir. Bu ayrım API'yi daha öngörülebilir hale getirir.

URI'lerde İsim Kullanmak

URI mümkün olduğunca resource isimlerinden oluşmalıdır. users açık bir örnektir. İşlem anlamı method tarafından taşınabilir. İsim kullanmak kalıp birliği sağlar. İstisnalar style guide içinde açıklanmalıdır.

Fiil Kullanımından Kaçınmak

createUser gibi URI'ler genellikle gereksizdir. POST method zaten oluşturma davranışını anlatabilir. Fiiller URI yapısını çeşitlendirebilir. Resource odaklı tasarım daha sade olur. Özel action gerektiğinde kontrollü istisna uygulanabilir.

Tekil mi Çoğul mu?

Tekil veya çoğul seçiminden çok tutarlılık önemlidir. REST API'lerde çoğul resource isimleri yaygın bir seçimdir. users koleksiyonu anlaşılırdır. users/{id} tek kaynağı temsil eder. Kurum genelinde aynı yaklaşım izlenmelidir.

kebab-case

Birden fazla kelimeli URI segmentlerinde kebab-case kullanılabilir. Örneğin payment-methods okunabilir bir yapıdır. Başka convention seçilecekse standardize edilmelidir. Aynı API içinde farklı biçimler kullanılmamalıdır. Case sensitivity davranışı ayrıca düşünülmelidir.

Nested Resources

Nested resource gerçek sahiplik ilişkisini gösterebilir. users/{id}/orders buna örnektir. Ancak her ilişki nesting gerektirmez. Çok uzun URI'ler kullanımı zorlaştırır. Bağımsız erişilebilir resource için düz endpoint daha uygun olabilir.

Maksimum Resource Derinliği

Derin nesting okunabilirliği azaltır. Yetkilendirme kuralları da daha zor anlaşılır hale gelebilir. İki veya üç segmentten sonra tasarım yeniden değerlendirilmelidir. Kesin sınır style guide içinde tanımlanabilir. İhtiyaç yoksa URL zinciri uzatılmamalıdır.

Consistent Naming

Aynı kavram her API'de aynı adla anılmalıdır. customer ve client gibi eş anlamlı kullanım kafa karıştırabilir. Domain sözlüğü oluşturmak faydalıdır. Schema alanları da bu sözlükle uyumlu olmalıdır. Tutarlılık ölçek büyüdükçe daha değerli hale gelir.

operationId Nasıl Standardize Edilmeli?

operationId küçük bir metadata alanı gibi görünse de SDK üretiminde büyük etki yaratır. Benzersiz ve öngörülebilir operationId isimleri generated client deneyimini iyileştirir. Kurum genelinde fiil artı resource kalıbı kullanılabilir. İsim değiştirmek API endpoint'i aynı kalsa bile SDK tarafında kırıcı değişiklik oluşturabilir. Bu nedenle operationId değerleri contract'ın önemli bir parçası olarak ele alınmalıdır.

operationId Nedir?

operationId bir operation için benzersiz tanımlayıcıdır. Tooling tarafından kullanılabilir. SDK method adına dönüşebilir. İnsan tarafından da okunmalıdır. Rastgele üretilen değerlerden kaçınılmalıdır.

SDK Generation ile İlişkisi

Generator operationId'yi method ismi olarak kullanabilir. Kötü isim SDK ergonomisini düşürür. İsim değişikliği client kodunu bozabilir. Bu nedenle naming convention önemlidir. SDK pipeline'ı değişikliği test etmelidir.

operationId Benzersiz Olmalı mı?

operationId pratikte benzersiz tutulmalıdır. Aynı değer generator conflict yaratabilir. Linter bunu kontrol edebilir. Global uniqueness kuralı kurum standardına eklenmelidir. Pull request aşamasında ihlal engellenmelidir.

Naming Convention

Naming convention basit ve tahmin edilebilir olmalıdır. Fiil resource yapısı iyi çalışır. Aynı işlem farklı servislerde benzer biçimde adlandırılmalıdır. Kısaltmalar kontrollü kullanılmalıdır. Style guide birkaç net örnek vermelidir.

listUsers

listUsers kullanıcı koleksiyonunu listeleme niyetini açıkça gösterir. SDK içinde kolay anlaşılır. GET koleksiyon operation'ıyla eşleşir. Benzer kaynaklarda aynı kalıp kullanılabilir. Pagination davranışı ayrıca response sözleşmesinde tanımlanmalıdır.

getUser

getUser tek kullanıcı getirme işlemini ifade eder. Resource kimliği parametre olarak alınır. İsim kısa ve açıktır. SDK tüketicisi davranışı tahmin edebilir. Aynı kalıp diğer detay endpoint'lerine uygulanabilir.

createUser

createUser yeni kullanıcı oluşturmayı anlatır. Genellikle POST operation ile eşleşir. Request schema ayrı modellenir. Response yeni resource'u döndürebilir. Naming pattern diğer create işlemlerinde korunmalıdır.

updateUser

updateUser güncelleme operation'ını tanımlar. PUT veya PATCH kullanımına göre semantik açıklanmalıdır. Aynı isim iki farklı operation için kullanılmamalıdır. Gerekirse patchUser gibi daha özel isim tercih edilebilir. Kurumsal kalıp önceden belirlenmelidir.

deleteUser

deleteUser silme işlemini açıkça gösterir. DELETE method ile doğal biçimde eşleşir. Soft delete varsa description bunu açıklamalıdır. SDK'da anlamlı bir method adı üretir. Değiştirilmesi breaking SDK değişikliği yaratabilir.

operationId Değişikliğinin SDK'lara Etkisi

operationId değişirse generated method adı değişebilir. Mevcut consumer kodu derlenmeyebilir. API endpoint aynı kalsa bile istemci açısından kırılma oluşabilir. Diff araçları bu değişikliği izlemelidir. Release notlarında etkisi açıkça belirtilmelidir.

Tags Nasıl Kullanılmalı?

Tags, API reference içinde gezinmeyi kolaylaştıran basit ama etkili bir bilgi mimarisi aracıdır. Tag yapısı rastgele bırakılırsa aynı domain farklı isimlerle bölünebilir. Resource veya domain bazlı bir strateji seçmek daha öngörülebilir sonuç verir. Bir operation'a gereksiz sayıda tag eklemek görünümü kalabalıklaştırır. Tag isimleri ve açıklamaları style guide içinde standardize edilmelidir.

Endpoint'leri Resource Bazlı Gruplama

Resource bazlı tag kolay anlaşılır. Users endpoint'leri Users altında toplanabilir. Tüketici aradığı operation'ı hızlı bulur. Benzer yapı diğer resource'larda tekrarlanabilir. Büyük API'lerde gezinme süresi azalır.

Domain Bazlı Tag

Domain tag daha geniş iş alanlarını temsil eder. Billing buna örnektir. Birden fazla resource aynı domain altında olabilir. Büyük sistemlerde mantıklı olabilir. Sınırlar açık tanımlanmalıdır.

Tek Operation'da Çok Fazla Tag Kullanmanın Sorunu

Çok fazla tag aynı operation'ı birçok yerde tekrar gösterebilir. UI kalabalıklaşır. Tüketici doğru kategori konusunda kararsız kalabilir. Primary grouping yaklaşımı daha sade olur. İstisnalar bilinçli seçilmelidir.

Tag Description

Tag description kapsamı açıklar. Hangi endpoint'lerin burada bulunduğunu anlatır. Domain sınırı belirtilebilir. Gereksiz uzun olmamalıdır. Developer portal içeriğine bağlantı verilebilir.

Tag Standardı

Tag isimleri ortak convention izlemelidir. Büyük küçük harf kullanımı tutarlı olmalıdır. Aynı kavram farklı adla tekrarlanmamalıdır. Lint kuralı uygulanabilir. Merkezi sözlük kullanmak büyük organizasyonlarda faydalıdır.

Parameters Nasıl Dokümante Edilmeli?

Parameter dokümantasyonunun amacı yalnızca ad ve veri tipi göstermek değildir. Parametrenin neden kullanıldığı, zorunlu olup olmadığı ve hangi değerleri kabul ettiği anlaşılmalıdır. Example ve default değerleri gerçek davranışla uyumlu olmalıdır. Özellikle pagination, filtering ve header parametreleri kurum çapında aynı semantiği taşımalıdır. Tutarlı parameter sözleşmesi consumer tarafındaki yanlış varsayımları azaltır.

Path Parameters

Path parameter URI'nin parçasıdır. Genellikle resource kimliğini taşır. Required olmalıdır. Formatı açıkça tanımlanmalıdır. Geçersiz değer durumundaki response belgelenmelidir.

Query Parameters

Query parameter filtreleme veya pagination için kullanılabilir. Optional davranışı açıklanmalıdır. Birden fazla değer desteği belirtilmelidir. Default varsa yazılmalıdır. Unsupported değer hatası standardize edilmelidir.

Header Parameters

Header parameter request metadata taşır. Correlation ID buna örnektir. Authentication header güvenlik scheme ile modellenebilir. Custom header isimleri standardize edilmelidir. Gereksiz header üretiminden kaçınılmalıdır.

Cookie Parameters

Cookie parameter browser tabanlı senaryolarda kullanılabilir. Güvenlik etkisi değerlendirilmelidir. SameSite ve benzeri davranışlar uygulama rehberinde açıklanabilir. OpenAPI konumu doğru tanımlanmalıdır. Public API'lerde gerçekten gerekli olup olmadığı sorgulanmalıdır.

required

required alanı consumer davranışını doğrudan etkiler. Yanlış değer generated client'ı da etkileyebilir. Zorunlu olmayan alan required yapılmamalıdır. Required değişiklikleri breaking change olabilir. Diff kontrolünde izlenmelidir.

description

Parameter description kullanım amacını açıklar. Adı tekrar etmek yeterli değildir. Kabul edilen davranış belirtilmelidir. Özel formatlar anlatılmalıdır. Kısa fakat bilgi taşıyan cümleler tercih edilmelidir.

schema

Schema veri tipini ve validation kurallarını tanımlar. Minimum ve maximum değerler eklenebilir. Enum değerleri belirtilebilir. Format kullanılabilir. Gerçek backend validation ile uyumlu olması gerekir.

example

Example doğru kullanım örneği gösterir. Gerçek kişisel veri içermemelidir. Schema ile uyumlu olmalıdır. CI içinde doğrulanması faydalıdır. Stale example problemi düzenli testle azaltılabilir.

Default Values

Default değer gerçek sunucu davranışını yansıtmalıdır. Dokümana hayali default eklenmemelidir. Pagination limitinde sık kullanılır. Değişiklik consumer davranışını etkileyebilir. Release notunda açıklanması gerekebilir.

Request Body Nasıl Standardize Edilmeli?

Request body sözleşmesi API consumer'ın en çok hata yaptığı alanlardan biridir. Content-Type, schema ve required alanların açıkça belirtilmesi gerekir. Create ve update modelleri her zaman aynı schema olmak zorunda değildir. Örnek request verisi gerçek kullanım senaryosuna yakın olmalıdır. Standardizasyon yapıldığında frontend, mobil ve partner ekiplerinin payload oluşturma süreci önemli ölçüde kolaylaşır.

requestBody

requestBody operation'ın gönderdiği payload'ı tanımlar. Required durumu açık olmalıdır. Birden fazla media type içerebilir. Schema reusable component olabilir. Description iş kuralını kısaca anlatmalıdır.

Content-Type

Content-Type payload formatını belirtir. Sunucunun desteklediği değerler belgelenmelidir. Gereksiz formatlar eklenmemelidir. Client üretimi bu bilgiden yararlanabilir. Gerçek implementation ile aynı olmalıdır.

application/json

application/json REST API'lerde yaygın bir seçimdir. Schema JSON payload'ı tanımlar. Encoding davranışı belirli olmalıdır. Tarih formatları standardize edilmelidir. Örnekler geçerli JSON olmalıdır.

multipart/form-data

multipart/form-data dosya yükleme senaryolarında kullanılabilir. Binary alanlar doğru modellenmelidir. Dosya boyutu sınırı açıklanmalıdır. Ek metadata alanları schema içinde gösterilmelidir. Güvenlik kontrolleri uygulama tarafında ayrıca yapılmalıdır.

Schema

Request schema payload yapısını tanımlar. Alan tipleri açık olmalıdır. Nested objeler reusable yapılabilir. Validation kuralları eklenmelidir. Create ve patch ihtiyaçları ayrı değerlendirilebilir.

Required Fields

Required field gönderilmesi zorunlu alandır. Gerçek validation davranışıyla eşleşmelidir. Gereksiz required alan consumer esnekliğini azaltır. Sonradan required eklemek breaking change olabilir. Contract review bu değişikliği incelemelidir.

Optional Fields

Optional alanın gönderilmemesi desteklenmelidir. Null ile absent aynı anlamda olmayabilir. Bu fark description içinde açıklanmalıdır. Default davranış varsa belirtilmelidir. Generated client tipleri bu modelden etkilenebilir.

Request Examples

Request example geliştirici için güçlü öğrenme aracıdır. Minimum çalışan örnek sunulabilir. Daha gelişmiş örnekler ayrıca eklenebilir. Secret veya gerçek kişisel veri kullanılmamalıdır. CI validation örneklerin güncel kalmasına yardımcı olur.

Response Dokümantasyonu Nasıl Yapılmalı?

Response tarafında yalnızca başarılı 200 cevabını göstermek ciddi bir dokümantasyon eksikliğidir. Consumer hangi hata kodlarını alabileceğini ve hata gövdesini nasıl parse edeceğini bilmelidir. Success schema, response headers ve örnek payload birlikte açıklanmalıdır. Empty response davranışı da açık olmalıdır. Özellikle partner API'lerinde hata cevaplarının eksiksiz belgelenmesi entegrasyon süresini belirgin biçimde azaltır.

Success Response

Başarılı response beklenen sonucu tanımlar. Veri modeli açık olmalıdır. Örnek payload eklenmelidir. Status code doğru seçilmelidir. Operation semantiğiyle uyum korunmalıdır.

HTTP Status Code

Status code HTTP semantiğini yansıtmalıdır. Aynı durum farklı endpoint'lerde farklı kodla ifade edilmemelidir. Kurumsal katalog oluşturulabilir. Consumer davranışı buna göre şekillenir. Hatalı seçim gereksiz client mantığı üretir.

Response Schema

Response schema dönen veri yapısını tanımlar. Required alanlar dikkatle seçilmelidir. Field kaldırmak breaking change olabilir. Reusable component kullanmak tutarlılığı artırır. Runtime contract testleri schema uyumunu doğrulayabilir.

Response Headers

Response headers önemli metadata taşıyabilir. Rate limit bilgisi buna örnektir. Correlation ID de header içinde dönebilir. Header açıklaması ve formatı belgelenmelidir. Client için gerekli davranış açık olmalıdır.

Response Example

Response example gerçekçi veri göstermelidir. Schema ile uyumlu olmalıdır. PII içermemelidir. Birden fazla senaryo için ayrı örnek eklenebilir. Test edilerek güncelliği korunmalıdır.

Empty Response

Bazı operation'lar body döndürmez. Bu durum açıkça gösterilmelidir. 204 kullanımı buna örnektir. Client boş body parse etmeye çalışmamalıdır. Framework davranışı spec ile eşleşmelidir.

Her Endpoint İçin Hata Cevapları

Her operation olası hata cevaplarını göstermelidir. 400 ve 401 gibi ortak hatalar reusable olabilir. Domain conflict hataları ayrıca belirtilmelidir. Hata schema aynı kalmalıdır. Consumer sürpriz response ile karşılaşmamalıdır.

HTTP Status Code Standardizasyonu

Status code standardizasyonu farklı servislerin aynı dili konuşmasını sağlar. Tüketici her endpoint için yeni hata yorumlama kuralı yazmak zorunda kalmamalıdır. Kurum genelinde hangi senaryonun hangi status code ile temsil edileceği açıkça tanımlanmalıdır. Bu kurallar mümkün olduğunda contract testleriyle doğrulanmalıdır. Özellikle 400, 409 ve 422 ayrımı ekiplerin üzerinde uzlaşması gereken konulardan biridir.

200 OK

200 başarılı request için yaygın bir response'dur. Body genellikle bulunur. GET operation'larında sık kullanılır. Her başarı durumunu otomatik olarak 200 yapmak doğru değildir. Operation semantiği değerlendirilmelidir.

201 Created

201 yeni resource oluşturulduğunu ifade eder. POST create işlemlerinde uygundur. Oluşturulan resource döndürülebilir. Location header kullanılabilir. Kurum standardı davranışı netleştirmelidir.

202 Accepted

202 request'in kabul edildiğini fakat işlemin tamamlanmadığını gösterir. Asenkron işlerde kullanılabilir. Job status endpoint'i belgelenebilir. Consumer tamamlanma sonucunu nasıl takip edeceğini bilmelidir. 202 doğrudan başarılı iş sonucu olarak yorumlanmamalıdır.

204 No Content

204 başarılı fakat body içermeyen response'dur. DELETE operasyonlarında kullanılabilir. Client body beklememelidir. Spec boş response'u doğru göstermelidir. Gereksiz JSON gövdesi eklenmemelidir.

400 Bad Request

400 request'in temel olarak geçersiz olduğunu gösterebilir. Syntax hataları burada ele alınabilir. Kurumsal ayrım açık olmalıdır. Hata body standard error schema kullanmalıdır. Kullanıcıya düzeltilebilir bilgi verilmelidir.

401 Unauthorized

401 genellikle kimlik doğrulama eksik veya geçersiz olduğunda kullanılır. Yetki yetersizliğiyle karıştırılmamalıdır. Authentication scheme dokümante edilmelidir. Error code client'a yol göstermelidir. Token yenileme rehberi ayrıca bulunabilir.

403 Forbidden

403 kimliği bilinen istemcinin ilgili kaynağa yetkisi olmadığını gösterebilir. Authorization davranışı açık olmalıdır. 401 ile ayrım korunmalıdır. Hassas kaynaklarda bilgi sızıntısı etkisi düşünülmelidir. Kurumsal güvenlik standardıyla uyumlu kullanılmalıdır.

404 Not Found

404 resource bulunmadığında kullanılabilir. Bazı güvenlik senaryolarında erişilemeyen resource da 404 dönebilir. Bu tercih belgelenmelidir. Aynı API içinde tutarlı davranılmalıdır. Error schema yine ortak formatı kullanmalıdır.

409 Conflict

409 mevcut sistem durumuyla conflict olduğunu ifade edebilir. Duplicate resource buna örnektir. Optimistic locking senaryolarında da kullanılabilir. Machine-readable error code verilmelidir. Client'ın nasıl toparlanacağı açıklanmalıdır.

422 Unprocessable Content

422 semantik validation hataları için kullanılabilir. Kullanım politikası kurum içinde net olmalıdır. Field-level errors response içinde gösterilebilir. 400 ile ayrım belgelenmelidir. Tüm ekipler aynı yaklaşımı uygulamalıdır.

429 Too Many Requests

429 rate limit aşıldığında kullanılır. Retry-After bilgisi faydalı olabilir. Limit modeli dokümante edilmelidir. Client kontrolsüz retry yapmamalıdır. SDK bu davranışı destekleyebilir.

500 Internal Server Error

500 beklenmeyen sunucu hatasını ifade eder. Dahili stack trace döndürülmemelidir. Correlation ID eklenebilir. Consumer genel hata formatını almalıdır. Operasyon ekibi log üzerinden ayrıntıya ulaşmalıdır.

Aynı Durum İçin Farklı Status Code Kullanmamak

Tutarsız status code client kodunu gereksiz büyütür. Aynı validation hatası aynı anlamı taşımalıdır. Style guide karar tablosu içerebilir. Linter bazı kuralları kontrol edebilir. Contract testleri runtime davranışını doğrulayabilir.

API Error Response Formatı Nasıl Standardize Edilmeli?

Standart hata modeli consumer deneyimi açısından en değerli kurumsal API kurallarından biridir. Her servis farklı error body üretirse ortak SDK ve izleme mekanizmaları zorlaşır. Hata modelinde insan tarafından okunabilir mesaj ile makine tarafından işlenebilir kod birbirinden ayrılmalıdır. Correlation ID destek ekiplerinin olay kaydını bulmasına yardımcı olur. Ortak Error schema tüm API'lerde reusable component olarak kullanılabilir.

Error Code

Error code hatayı programatik olarak ayırt etmeye yardımcı olur. HTTP status ile aynı şey değildir. Domain hatasını ifade edebilir. Kararlı olmalıdır. Dokümante edilmiş katalogda bulunması faydalıdır.

Human-Readable Message

Message geliştirici veya kullanıcı için anlaşılır açıklamadır. Değişebilir metin olarak değerlendirilmelidir. Client mantığı message üzerinde kurulmammalıdır. Hassas sistem ayrıntıları verilmemelidir. Yerelleştirme ihtiyacı ayrıca düşünülmelidir.

Machine-Readable Code

Machine-readable code uygulamanın karar vermesini sağlar. Örneğin USER_ALREADY_EXISTS gibi bir kod kullanılabilir. Kararlı tutulmalıdır. Dokümante edilmelidir. Aynı hata farklı servislerde farklı kodla temsil edilmemelidir.

Details

Details hata hakkında ek bağlam taşıyabilir. Yapısı belirli olmalıdır. Serbest ve kontrolsüz veri alanına dönüşmemelidir. Hassas bilgi içermemelidir. Gerekirse alt schema tanımlanmalıdır.

Field-Level Validation Errors

Field-level error hangi alanın geçersiz olduğunu gösterir. Form entegrasyonlarında çok değerlidir. Field path açık verilmelidir. Error reason machine-readable olabilir. Birden fazla hata array içinde döndürülebilir.

Correlation ID

Correlation ID request'i loglar arasında takip etmeyi sağlar. Consumer destek talebinde bu değeri paylaşabilir. Response header veya body içinde bulunabilir. Format standardize edilmelidir. PII olarak tasarlanmamalıdır.

Documentation Link

Dokümantasyon bağlantısı hata hakkında ek rehber sunabilir. Özellikle karmaşık domain hatalarında faydalıdır. URL kalıcı olmalıdır. Kırık link testi yapılmalıdır. Her küçük hata için zorunlu olmak zorunda değildir.

Ortak Error Schema

Ortak schema tüm API'lerin aynı hata modelini kullanmasını sağlar. Merkezi component library içinde tutulabilir. Versiyonlanmalıdır. Breaking değişiklik kontrollü yapılmalıdır. Generated SDK aynı modeli tekrar kullanabilir.

Validation Error Standardı

Validation hatası yalnızca “invalid request” mesajıyla bırakılmamalıdır. Consumer hangi alanın neden reddedildiğini anlayabilmelidir. Beklenen format ve geçerli aralık mümkün olduğunda response veya dokümantasyon üzerinden bulunmalıdır. Birden fazla hata tek response içinde taşınabilir. Nested alanlarda path standardı tanımlamak frontend ve mobil ekipleri için önemli kolaylık sağlar.

Hangi Alan Hatalı?

Hata response'u ilgili field'i göstermelidir. Path formatı tutarlı olmalıdır. Nested alanlar nokta veya JSON Pointer ile belirtilebilir. Kurum bir convention seçmelidir. Consumer bu değeri UI alanına eşleyebilmelidir.

Hata Nedeni

Reason yalnızca “invalid” dememelidir. Eksik değer veya format problemi ayrıştırılmalıdır. Machine code kullanılabilir. Human-readable mesaj eklenebilir. Backend ayrıntısı sızdırılmamalıdır.

Expected Format

Beklenen format kullanıcıya doğru değeri üretme şansı verir. Tarih formatı buna örnektir. Enum seçenekleri gösterilebilir. Minimum uzunluk belirtilebilir. Schema bilgisiyle aynı olmalıdır.

Birden Fazla Validation Error

Bir request birden fazla hata içerebilir. Hepsini tek response'ta döndürmek kullanıcı deneyimini iyileştirebilir. Errors array modeli kullanılabilir. Sıralama garantisi varsa belirtilmelidir. Client belirli sıraya bağımlı olmamalıdır.

Nested Field Errors

Nested object hatalarında field path önemlidir. address.city gibi gösterim kullanılabilir. Array index davranışı belirlenebilir. Format tüm servislerde aynı olmalıdır. Frontend mapping işlemi böylece sadeleşir.

Error Code Kataloğu

Error code kataloğu merkezi referans sağlar. Her kodun anlamı açıklanmalıdır. İlgili HTTP status gösterilmelidir. Deprecated kodlar işaretlenmelidir. Yeni kod ekleme süreci yönetilmelidir.

components Bölümü Neden Önemlidir?

components bölümü spec tekrarını azaltmanın ana aracıdır. Aynı error schema onlarca operation içinde yeniden yazılmamalıdır. Reusable modeller değişiklik yönetimini kolaylaştırır. Kurumsal API standardında ortak pagination, security ve error bileşenlerini merkezi bir library üzerinden sunmak güçlü bir yaklaşımdır. Yine de aşırı paylaşım domain sınırlarını bozabileceği için gerçekten ortak olan yapıların seçilmesi gerekir.

Reusable Schemas

Reusable schema ortak veri modelini merkezi hale getirir. Kopya tanımları azaltır. Güncelleme tek noktadan yapılabilir. $ref ile kullanılabilir. Versiyon yönetimi dikkatle yapılmalıdır.

Reusable Parameters

Pagination limit gibi ortak parametreler reusable olabilir. Description tutarlılığı sağlanır. Default değer tek noktada tutulur. Gereksiz copy paste azalır. Her endpoint'in gerçekten aynı semantiği kullandığı doğrulanmalıdır.

Reusable Responses

401 veya 500 gibi ortak response'lar reusable olabilir. Error schema tekrar edilmez. Description standardize edilir. Header bilgileri merkezi tutulabilir. Domain-specific response'lar ayrı kalmalıdır.

Reusable Headers

Correlation ID gibi header'lar reusable tanımlanabilir. Format her API'de aynı olur. Rate limit header'ları da standardize edilebilir. Açıklamalar tek noktadan yönetilir. Client generation tutarlılığı artar.

Reusable Security Schemes

Security scheme tanımı components içinde yer alır. Bearer veya OAuth yapıları merkezi convention izleyebilir. Gerçek secret bulunmamalıdır. Scheme isimleri tutarlı olmalıdır. Operation security requirement bu tanımlara referans verir.

Tekrarı Azaltmak

Tekrar bakım maliyeti yaratır. Aynı schema farklı kopyalarda zamanla ayrışabilir. Reuse spec drift riskini azaltır. Ancak her benzer model ortaklaştırılmamalıdır. Semantik olarak aynı olan yapılar paylaşılmalıdır.

Kurumsal Component Library

Merkezi library ortak API yapılarını paketleyebilir. Error ve pagination modelleri buna uygundur. Versiyonlanmış biçimde dağıtılmalıdır. Consumer ekipler değişikliklerden haberdar edilmelidir. Pipeline uyumluluk kontrolü yapmalıdır.

$ref Nasıl Kullanılır?

$ref OpenAPI dosyasındaki tekrar kullanılabilir tanımlara referans vermeyi sağlar. Büyük API'lerde dosya boyutunu ve kopya schema sayısını azaltır. Local ve external reference seçenekleri farklı repository yapıları için kullanılabilir. Reference zinciri aşırı uzatılırsa geliştiricinin spec'i takip etmesi zorlaşabilir. Bu nedenle DRY yaklaşımı ile okunabilirlik arasında dengeli bir yapı kurulmalıdır.

Local Reference

Local reference aynı belge içindeki tanıma gider. components schemas sık kullanılan hedeftir. Basit ve taşınabilirdir. Tooling desteği genellikle iyidir. İsimlerin açık olması okunabilirliği artırır.

External Reference

External reference başka dosyadaki tanıma işaret eder. Multi-file spec yapısında faydalıdır. Dosya yolları build ortamında çözülmelidir. Remote reference güvenilirlik açısından değerlendirilmelidir. CI bundling işlemi uygulanabilir.

Shared Schema

Shared schema birden fazla operation tarafından kullanılabilir. User gibi ortak resource modeli buna örnektir. Copy paste azalır. Breaking değişiklik etkisi daha görünür olur. Domain sınırına dikkat edilmelidir.

Ortak Error Response

Error response ideal reuse adaylarından biridir. Aynı status davranışı korunur. Schema merkezi tutulur. Correlation ID standardı paylaşılır. Hata kataloğu ile uyumlu olmalıdır.

Ortak Pagination Schema

Pagination metadata ortak component olabilir. nextCursor ve hasMore gibi alanlar standardize edilir. Liste endpoint'leri aynı yapıyı kullanır. Client helper geliştirmek kolaylaşır. Farklı pagination tipi gerekiyorsa açık istisna tanımlanmalıdır.

$ref Kullanımında Döngüler

Schema ilişkileri döngüsel olabilir. Bazı araçlar bunu farklı işler. Recursive model gerçekten gerekiyorsa tooling testi yapılmalıdır. Gereksiz circular reference'tan kaçınılmalıdır. Code generation sonucu kontrol edilmelidir.

Specification'ı DRY Tutmak

DRY yaklaşımı tekrar eden sözleşmeyi azaltır. Her benzer alanı paylaşmak ise aşırı soyutlama yaratabilir. Gerçek semantik ortaklık aranmalıdır. Review sırasında reuse sınırı değerlendirilmelidir. Okunabilirlik her zaman korunmalıdır.

Schema Tasarımı Nasıl Standardize Edilir?

Schema tasarımı API sözleşmesinin veri dilidir. Aynı kavramın farklı servislerde farklı tipe dönüşmesi consumer tarafında gereksiz dönüşüm kodu yaratır. Primitive type kullanımı, format tercihleri, null davranışı ve composition kuralları style guide içinde tanımlanmalıdır. JSON Schema uyumu kullanılan OpenAPI sürümüne göre değerlendirilmelidir. Schema değişiklikleri breaking change analizinin de temel girdilerinden biridir.

string

string metinsel veriler için kullanılır. Format gerektiğinde eklenebilir. Uzunluk sınırları belirtilebilir. Pattern dikkatli kullanılmalıdır. ID gibi sayısal görünse de metin olan değerler string olabilir.

integer

integer tam sayı değerlerini ifade eder. Minimum ve maximum tanımlanabilir. Format ihtiyaca göre eklenebilir. Para için doğrudan integer kullanımı para birimi modeliyle düşünülmelidir. Public contract'ta sınırlar açık olmalıdır.

number

number ondalıklı değerleri temsil edebilir. Floating point davranışı dikkate alınmalıdır. Finansal değerlerde precision ihtiyacı ayrıca değerlendirilmelidir. Unit description içinde belirtilmelidir. Aynı alan farklı API'lerde farklı unit kullanmamalıdır.

boolean

boolean iki durumlu değerler için uygundur. Field adı anlamlı olmalıdır. isActive gibi okunabilir isim kullanılabilir. Null üçüncü durum yaratacaksa bilinçli modellenmelidir. Default davranış açıklanmalıdır.

array

array birden fazla öğeyi taşır. Items schema açıkça tanımlanmalıdır. Maksimum eleman sayısı gerekiyorsa belirtilmelidir. Sıralamanın anlamı varsa açıklanmalıdır. Empty array ile null ayrımı standardize edilmelidir.

object

object ilişkili alanları birlikte modeller. Properties açıkça tanımlanmalıdır. Additional properties davranışı bilinçli seçilmelidir. Nested object aşırı derin olmamalıdır. Reusable modeller components içine taşınabilir.

enum

enum izin verilen değer kümesini sınırlar. Client generation için değerlidir. Yeni değer eklenmesinin consumer etkisi değerlendirilmelidir. Tüketicinin bilinmeyen değere dayanıklı olması önerilir. Enum anlamları description içinde açıklanabilir.

format

format primitive type'a ek semantik verir. date-time buna örnektir. Tooling formatı farklı seviyelerde doğrulayabilir. Custom format dikkatli kullanılmalıdır. Beklenen gerçek değer örnekle gösterilmelidir.

nullable / null

Null modelleme OpenAPI sürümüne göre farklılaşır. Kullanılan sürümün semantiği takip edilmelidir. Null ile absent aynı şey değildir. Consumer açısından davranış açıklanmalıdır. Migration sırasında bu alan özellikle test edilmelidir.

oneOf

oneOf alternatif modellerden tam bir eşleşme ifade etmek için kullanılabilir. Polymorphic modellerde faydalıdır. Generator desteği kontrol edilmelidir. Discriminator kullanımı gerektiğinde değerlendirilmelidir. Gereksiz kullanım SDK kalitesini düşürebilir.

anyOf

anyOf birden fazla schema seçeneğine uyum sağlayabilir. Semantiği oneOf ile karıştırılmamalıdır. Tooling davranışı test edilmelidir. Consumer modelinin bunu rahat işleyip işlemediği değerlendirilmelidir. Basit model mümkünse tercih edilmelidir.

allOf

allOf schema composition için kullanılabilir. Ortak alanları birleştirmeye yardımcı olur. Inheritance benzeri kullanım araçlarda farklı sonuç verebilir. Generated modeller mutlaka incelenmelidir. Composition gereksiz derecede derinleştirilmemelidir.

Alan İsimlendirme Standardı

Field naming standardı API tüketicisinin bir servisten diğerine geçtiğinde aynı beklentiyle çalışmasını sağlar. camelCase veya snake_case seçeneklerinden biri kurum standardı olarak belirlenebilir. Boolean, tarih, ID ve enum alanları için ek kurallar tanımlamak faydalıdır. İsimler business kavramını açıkça yansıtmalıdır. Yeni API'lerde standardı baştan uygulamak, daha sonra geniş çaplı breaking migration yapmaktan daha ekonomiktir.

camelCase

camelCase JSON API'lerde sık kullanılan bir convention'dır. createdAt buna örnektir. JavaScript tüketicileri için doğal hissedebilir. Tüm alanlarda tutarlı uygulanmalıdır. Acronym davranışı ayrıca standardize edilmelidir.

snake_case

snake_case başka bir geçerli convention'dır. created_at buna örnektir. Özellikle bazı backend ekosistemlerinde doğal olabilir. Bir standardı seçmek önemlidir. Aynı contract içinde camelCase ile karıştırılmamalıdır.

Bir Standardı Seçip Her API'de Uygulamak

Asıl değer tek bir convention'ın tutarlı olmasıdır. Consumer dönüşüm kodu azalır. Shared schema kullanımı kolaylaşır. Linter field naming'i kontrol edebilir. İstisnalar açıkça belgelenmelidir.

Boolean Alanların İsimlendirilmesi

Boolean alan adı true durumunu anlaşılır kılmalıdır. isActive buna örnektir. Negatif isimlerden mümkün olduğunca kaçınılabilir. Double negative consumer kodunu zorlaştırır. Null kabul ediyorsa üçüncü durum açıklanmalıdır.

Tarih Alanları

Tarih isimleri zamanın anlamını göstermelidir. createdAt açık bir örnektir. date ile date-time ayrımı korunmalıdır. Timezone beklentisi belirtilmelidir. Tüm servislerde aynı convention kullanılmalıdır.

ID Alanları

ID alanı resource kimliğini açıkça göstermelidir. userId gibi isimler nested bağlamda faydalıdır. Format dokümante edilmelidir. Internal ve public ID ayrılabilir. Değişmezlik beklentisi belirtilmelidir.

Enum İsimleri

Enum alan isimleri domain kavramını ifade etmelidir. status tek başına bazen belirsiz olabilir. Değerler tutarlı casing kullanmalıdır. Yeni değer ekleme politikası açıklanmalıdır. Consumer unknown value stratejisi düşünülmelidir.

Tarih ve Saat Standardizasyonu

Tarih ve saat hataları dağıtık sistemlerde beklenenden daha maliyetli olabilir. Farklı timezone yorumları sıralama, raporlama ve süre hesaplamalarını etkiler. API contract içinde hangi alanın yalnızca tarih, hangisinin kesin zamanı temsil ettiği açık olmalıdır. ISO 8601 ve UTC temelli bir yaklaşım çoğu kurumsal sistem için anlaşılır bir başlangıç sağlar. Yerel timezone ihtiyacı varsa offset bilgisi açık biçimde taşınmalıdır.

ISO 8601

ISO 8601 yaygın tarih ve saat gösterim standardıdır. API'lerde taşınabilirlik sağlar. date-time alanları açık formatta tutulabilir. Example eklemek tüketiciyi yönlendirir. Parser uyumluluğu test edilmelidir.

UTC

UTC dağıtık sistemlerde ortak zaman tabanı sağlar. Sunucular arası karşılaştırmayı kolaylaştırır. Kullanıcı arayüzü yerel zamana dönüştürebilir. Contract bu beklentiyi açıkça yazmalıdır. Offset kaybına dikkat edilmelidir.

Timezone

Timezone iş kurallarında önemli olabilir. Randevu gibi senaryolar yalnız UTC değerinden daha fazla bilgi gerektirebilir. IANA timezone adı ayrıca saklanabilir. Beklenen kullanım açıklanmalıdır. Yerel saat ile absolute instant birbirine karıştırılmamalıdır.

date

date yalnızca takvim tarihini temsil eder. Doğum tarihi buna örnektir. Saat bilgisi eklenmemelidir. Timezone dönüşümüne ihtiyaç duymaz. Schema formatı buna uygun seçilmelidir.

date-time

date-time belirli bir zaman noktasını temsil eder. Timestamp alanlarında kullanılır. Offset veya UTC gösterimi açık olmalıdır. Example gerçek formatı göstermelidir. Consumer parser davranışı test edilmelidir.

Unix Timestamp Kullanmanın Avantaj ve Dezavantajları

Unix timestamp hesaplama açısından pratiktir. İnsan tarafından okunması zordur. Birim saniye veya milisaniye olabilir. Bu belirsizlik mutlaka önlenmelidir. Public API'lerde ISO 8601 çoğu zaman daha açıklayıcıdır.

createdAt ve updatedAt

createdAt oluşturma zamanını gösterir. updatedAt son değişikliği temsil eder. Formatları aynı olmalıdır. Server tarafından üretilmeleri yaygındır. Null ve ilk kayıt davranışı standardize edilmelidir.

ID Standardizasyonu

Resource ID seçimi yalnızca veritabanı tercihi değildir. Public API contract içine çıktıktan sonra yıllarca korunması gerekebilir. Integer, UUID ve ULID gibi seçeneklerin güvenlik, sıralama ve depolama etkileri vardır. Client tarafının ID üzerinde matematik yapmasına izin vermemek için public ID'yi string olarak modellemek bazı sistemlerde esneklik sağlar. En önemli kural, yayımlanan ID formatını gereksiz yere değiştirmemektir.

Integer ID

Integer ID basit ve küçüktür. Sıralı olabilir. Public kullanımda kaynak sayısı hakkında bilgi verebilir. Dağıtık üretim ihtiyacında ek strateji gerekebilir. Contract kararı veri tabanı detayından bağımsız düşünülmelidir.

UUID

UUID dağıtık sistemlerde kolay üretilebilir. Public resource identifier olarak yaygındır. String biçiminde belgelenebilir. Format açık olmalıdır. Consumer UUID yapısına gereksiz iş kuralı bağlamamalıdır.

ULID

ULID zaman sıralaması avantajı sağlayabilir. Metinsel formu vardır. Tooling ve veri tabanı desteği değerlendirilmelidir. Public contract'a çıkarılmadan önce uzun vadeli karar verilmelidir. Consumer için yine opaque identifier gibi ele alınması uygundur.

ID'yi String Olarak Dokümante Etmek

String model future migration esnekliği sağlayabilir. JavaScript number sınırları gibi sorunlardan kaçınılabilir. Consumer matematiksel işlem yapmaz. Format description içinde açıklanabilir. Server iç yapısı contract'a gereksiz bağlanmaz.

Internal ve Public ID Ayrımı

Internal ID veri tabanı için kullanılabilir. Public ID dış sözleşme için farklı olabilir. Bu ayrım güvenlik ve migration esnekliği sağlar. Mapping maliyeti vardır. Mimari ihtiyaçlara göre bilinçli karar verilmelidir.

Resource ID Formatını Değiştirmemek

ID formatı değişikliği consumer için büyük etki yaratabilir. Validation kodu bozulabilir. Cache key davranışı etkilenebilir. Migration stratejisi gerekebilir. Bu nedenle public ID uzun vadeli contract kararıdır.

Pagination Nasıl Standardize Edilmeli?

Pagination liste endpoint'lerinin performans ve kullanım modelini belirler. Her servis farklı parametre adı kullanırsa ortak client geliştirmek zorlaşır. Offset, page veya cursor yaklaşımlarından biri kullanım senaryosuna göre seçilmeli ve metadata modeli standardize edilmelidir. Büyük ve sık değişen veri setlerinde cursor yaklaşımı avantaj sağlayabilir. Hangi model seçilirse seçilsin tüm liste endpoint'lerinde mümkün olduğunca aynı contract korunmalıdır.

Offset-Based Pagination

Offset tabanlı model başlangıç konumunu belirtir. Uygulaması kolaydır. Büyük offset değerlerinde performans düşebilir. Veri değişirken kayıt atlama riski oluşabilir. Kullanım sınırları açıklanmalıdır.

Page-Based Pagination

Page tabanlı model kullanıcılar için anlaşılırdır. page ve size benzeri parametreler kullanılır. Arkada offset modeline dönüşebilir. Dinamik veri setlerinde aynı tutarlılık sorunlarını yaşayabilir. UI pagination için uygun olabilir.

Cursor-Based Pagination

Cursor modeli sonraki konumu opaque token ile gösterir. Büyük veri setlerinde verimli olabilir. Cursor formatı consumer tarafından yorumlanmamalıdır. Expiration davranışı açıklanmalıdır. Sıralama kuralı kararlı olmalıdır.

limit

limit döndürülecek maksimum kayıt sayısını belirler. Default ve maximum değer belirtilmelidir. Aşırı değerlerde hata veya clamp davranışı açıklanmalıdır. Tüm endpoint'lerde benzer sınırlar tercih edilebilir. Performans bütçesi dikkate alınmalıdır.

cursor

cursor sonraki sayfanın başlangıç token'ıdır. Opaque değer olmalıdır. Client içeriğini parse etmemelidir. Geçersiz cursor hatası standardize edilmelidir. Güvenlik açısından tahmin edilebilir veri sızdırmamalıdır.

nextCursor

nextCursor sonraki istekte kullanılacak token'ı taşır. Son sayfada null olabilir. Bu davranış belgelenmelidir. hasMore ile birlikte kullanılabilir. Response schema tüm liste endpoint'lerinde aynı olmalıdır.

hasMore

hasMore başka sayfa olup olmadığını gösterir. Boolean olarak modellenebilir. nextCursor ile semantik uyumlu olmalıdır. Son sayfada davranış net olmalıdır. Client döngüsünü sadeleştirir.

Total Count

Total count kullanıcı arayüzünde faydalı olabilir. Büyük veri setlerinde maliyetli olabilir. Her response'ta hesaplanması zorunlu olmamalıdır. Yaklaşık sayı kullanılıyorsa belirtilmelidir. Cursor modelinde gerçekten gerekli olup olmadığı değerlendirilmelidir.

Tüm Liste Endpoint'lerinde Aynı Pagination Modeli

Ortak model consumer kodunu önemli ölçüde sadeleştirir. SDK reusable pagination helper sunabilir. Parametre isimleri tahmin edilebilir olur. İstisnalar açıkça belgelenmelidir. Style guide pagination bölümünü zorunlu hale getirmelidir.

Filtering ve Sorting Standardı

Filtering ve sorting kuralları büyüyen API'lerde hızla tutarsız hale gelebilir. Bir endpoint status, diğeri filterStatus kullanıyorsa tüketici her resource için yeni convention öğrenir. Ortak filter, sort, search ve date range kalıpları belirlenmelidir. Desteklenmeyen alanlara sessizce cevap vermek yerine açık hata üretmek daha güvenli olabilir. Query standardı API style guide'ın temel bölümlerinden biri olmalıdır.

Filter Parameters

Filter parameter alan veya kriter bazlı daraltma sağlar. İsim convention'ı sabit olmalıdır. Desteklenen değerler açıklanmalıdır. Index yapısı performansı etkileyebilir. Her database alanı otomatik public filter yapılmamalıdır.

Multiple Filters

Birden fazla filter birlikte kullanılabilir. AND veya OR semantiği açıklanmalıdır. Tek parametrede çoklu değer desteği belirlenmelidir. URL encoding örneklenmelidir. Karmaşık query DSL gereksiz yere oluşturulmamalıdır.

Sort Field

Sort field izin verilen sıralama alanını belirler. Arbitrary field kabul etmek risk yaratabilir. Desteklenen alanlar enum gibi belgelenebilir. Default sıralama açık olmalıdır. Stable sort için tie breaker düşünülebilir.

Sort Direction

Sort direction ascending veya descending olabilir. asc ve desc gibi değerler standardize edilmelidir. Default yön belirtilmelidir. Case davranışı açık olmalıdır. Aynı convention her API'de korunmalıdır.

Search Parameter

Search serbest metin aramasını temsil edebilir. Hangi alanlarda çalıştığı belirtilmelidir. Minimum karakter sınırı olabilir. Case sensitivity açıklanmalıdır. Full-text search davranışı database detaylarından bağımsız anlatılmalıdır.

Date Range

Date range başlangıç ve bitiş parametreleriyle modellenebilir. Inclusive sınırlar açıklanmalıdır. Timezone davranışı belirtilmelidir. Maksimum aralık performans için sınırlandırılabilir. İsimler tüm endpoint'lerde aynı kalmalıdır.

Unsupported Filter Errors

Desteklenmeyen filter sessizce yok sayılmamalıdır. Açık validation hatası geliştiriciyi yönlendirir. Machine-readable error code kullanılabilir. Geçerli filter listesi belirtilir. Bu davranış tüm API'lerde aynı olmalıdır.

Idempotency Nasıl Dokümante Edilmeli?

Idempotency özellikle ödeme, sipariş ve benzeri tekrarın maliyetli olduğu işlemlerde önemlidir. Network timeout sonrasında consumer aynı request'i tekrar göndermek zorunda kalabilir. Sunucunun duplicate işlem üretmemesi için idempotency key modeli kullanılabilir. Header adı, geçerlilik süresi ve aynı key ile farklı payload gönderildiğinde oluşacak davranış açıkça belgelenmelidir. Bu konu yalnız backend implementasyonu değil, API contract'ın parçasıdır.

Idempotency Nedir?

Idempotency aynı işlemin tekrarında istenmeyen ek etki oluşmamasıdır. Retry senaryolarında önemlidir. HTTP method semantiğiyle ilişkilidir. API behavior açıkça belgelenmelidir. Consumer güvenli retry yapabilmelidir.

PUT ve DELETE

PUT ve DELETE idempotent semantiğe sahip olacak şekilde tasarlanabilir. Aynı request tekrarlandığında nihai durum değişmemelidir. Error davranışı yine farklı olabilir. Implementation bunu desteklemelidir. Contract testleri kritik senaryoları doğrulayabilir.

POST İçin Idempotency Key

POST doğal olarak idempotent olmak zorunda değildir. Duplicate oluşturmanın sorun olduğu yerde key kullanılabilir. Client her business operation için benzersiz değer üretir. Server sonucu belirli süre saklayabilir. Davranış dokümantasyonda ayrıntılı açıklanmalıdır.

Idempotency-Key Header

Header ismi kurum genelinde standardize edilmelidir. Format kısıtları belirtilmelidir. Maksimum uzunluk tanımlanabilir. Reuse davranışı açıklanmalıdır. Security loglarında hassas veri içermemesi sağlanmalıdır.

Retry Sonrası Duplicate İşlemi Önlemek

Client timeout sonucu cevabı alamamış olabilir. Aynı key ile retry güvenli olmalıdır. Server önceki sonucu döndürebilir. Conflict davranışı gerektiğinde tanımlanabilir. Payment gibi kritik operasyonlarda bu sözleşme özellikle önemlidir.

Idempotency Süresi

Key sonsuza kadar saklanmak zorunda değildir. Retention süresi dokümante edilmelidir. Süre dolduğunda davranış açık olmalıdır. Consumer retry politikasını buna göre ayarlayabilir. Süre business riskine göre seçilmelidir.

Rate Limiting Nasıl Dokümante Edilmeli?

Rate limiting yalnızca altyapı konfigürasyonu olarak bırakılmamalıdır. API tüketicisi hangi limite tabi olduğunu ve limit aşıldığında ne yapacağını bilmelidir. Request limiti tenant veya API key bazında uygulanabilir. 429 response, Retry-After ve varsa rate limit header'ları contract içinde belgelenmelidir. Bu bilgiler SDK retry stratejisinin güvenli hazırlanmasına da yardımcı olur.

Rate Limit Nedir?

Rate limit belirli sürede kabul edilen request miktarını sınırlar. Sistemi korur. Adil kullanım sağlar. Consumer kapasite planı yapabilir. Limit değerleri mümkünse açıkça belgelenmelidir.

Request Limiti

Limit dakika veya saniye bazlı olabilir. Window modeli açıklanmalıdır. Endpoint bazlı farklılıklar belirtilebilir. Default limit net olmalıdır. Değişiklikler önceden duyurulmalıdır.

Tenant / API Key Bazlı Limit

Limit tenant bazında uygulanabilir. API key bazlı model de mümkündür. Consumer hangi kimliğin sayıldığını bilmelidir. Shared credential durumunda etki büyüyebilir. Kurumsal planlar varsa farklı limitler belgelenebilir.

429 Too Many Requests

Limit aşıldığında 429 kullanılabilir. Error body standart formatı izlemelidir. Retry bilgisi verilmelidir. Client exponential backoff kullanabilir. Kontrolsüz retry önlenmelidir.

Retry-After

Retry-After tekrar deneme zamanını gösterir. Format HTTP standardıyla uyumlu olmalıdır. Client bu değeri dikkate alabilir. Her 429 response'ta bulunup bulunmadığı açıklanmalıdır. SDK desteği sağlanabilir.

Rate Limit Headers

Header'lar kalan kota bilgisini taşıyabilir. İsimler kurum genelinde standardize edilmelidir. Semantik açık olmalıdır. Window reset zamanı belirtilmelidir. Public API consumer'ı buna göre davranabilir.

Burst Limit

Burst limit kısa süredeki ani trafik artışını sınırlar. Uzun dönem quota'dan farklıdır. Consumer bunu bilmelidir. Retry stratejisi farklı olabilir. Dokümanda iki limit birbirine karıştırılmamalıdır.

Quota

Quota daha uzun dönemli kullanım sınırıdır. Günlük veya aylık olabilir. Yenilenme zamanı belirtilmelidir. Limit artışı süreci varsa açıklanmalıdır. 429 veya farklı business response politikası standardize edilmelidir.

API Authentication Swagger'da Nasıl Dokümante Edilir?

Authentication dokümantasyonu entegrasyonun en hassas bölümlerinden biridir. OpenAPI securitySchemes ile API key, bearer token, OAuth 2.0, OpenID Connect ve diğer yöntemler modellenebilir. Global security requirement varsayılan politikayı tanımlar, operation-level security ise gerekli istisnaları gösterebilir. Gerçek token ve production credential hiçbir zaman specification içine örnek olarak konulmamalıdır. Kimlik doğrulama rehberi yalnız schema değil, credential alma ve yenileme sürecini de açıklamalıdır.

securitySchemes

securitySchemes desteklenen authentication yöntemlerini tanımlar. Components altında bulunur. Scheme isimleri anlamlı olmalıdır. Gerçek secret içermez. Operations bu tanımlara referans verir.

API Key

API key header veya query üzerinden taşınabilir. Header kullanımı genellikle daha kontrollüdür. Key adı açık belirtilmelidir. Gerçek key example olarak yazılmamalıdır. Rotation süreci rehberde anlatılabilir.

Bearer Token

Bearer token Authorization header içinde taşınır. Scheme doğru modellenmelidir. Token formatı gerekirse açıklanabilir. Example gerçek credential içermemelidir. Expiration ve refresh davranışı ayrıca belgelenmelidir.

JWT

JWT bearer token olarak kullanılabilir. API'nin JWT iç yapısına gereksiz bağımlılığı olmamalıdır. Gerekli claim'ler açıklanabilir. Token doğrulama consumer sorumluluğu değilse gereksiz ayrıntı verilmemelidir. Güvenlik rehberi ayrı tutulabilir.

Basic Authentication

Basic authentication basit HTTP authentication yöntemidir. HTTPS olmadan kullanılmamalıdır. Credential örnekleri gerçek olmamalıdır. Modern public API'lerde kullanım ihtiyacı dikkatle değerlendirilmelidir. Legacy sistemlerde açıkça belgelenebilir.

OAuth 2.0

OAuth 2.0 farklı flow seçenekleri sunar. Kullanılan flow API senaryosuna göre seçilmelidir. Scope'lar açık tanımlanmalıdır. Authorization ve token URL'leri doğru olmalıdır. Swagger UI yapılandırması güvenlik politikasıyla uyumlu yapılmalıdır.

OpenID Connect

OpenID Connect kimlik katmanı ihtiyaçlarında kullanılabilir. Discovery URL tanımlanabilir. API authorization modeliyle ilişkisi açıklanmalıdır. Consumer gerekli scope'ları bilmelidir. Tooling desteği test edilmelidir.

Mutual TLS

Mutual TLS istemci sertifikasıyla karşılıklı doğrulama sağlar. Kurumsal veya partner entegrasyonlarında kullanılabilir. Sertifika provisioning süreci ayrıca belgelenmelidir. OpenAPI security scheme ile gösterilebilir. Credential dağıtımı spec dışında yönetilmelidir.

Global Security Requirement

Global security çoğu operation için varsayılan gereksinimi tanımlar. Tekrarı azaltır. Public operation gerektiğinde override edilebilir. Yanlış global tanım tüm dokümanı etkileyebilir. Lint kuralıyla doğrulanması faydalıdır.

Operation-Level Security

Operation-level security özel yetki gereksinimini belirtir. Farklı scope burada gösterilebilir. Public endpoint boş security kullanabilir. İstisnalar bilinçli olmalıdır. Review sırasında güvenlik ekibi tarafından değerlendirilebilir.

OAuth 2.0 Swagger/OpenAPI Tanımı

OAuth 2.0 tanımı yalnızca token URL yazıp bırakılmamalıdır. Kullanılan flow, scope, authorization URL ve token URL birlikte düşünülmelidir. Swagger UI üzerinden authorization akışı çalıştırılacaksa redirect ve client yapılandırması güvenli yapılmalıdır. Public client secret tarayıcı tarafına gömülmemelidir. Production credential değerlerinin specification veya frontend kaynak kodu içine yazılmaması temel güvenlik kuralıdır.

Authorization Code

Authorization Code kullanıcı adına yetkilendirme gereken akışlarda kullanılabilir. Browser redirect içerir. PKCE ihtiyacı değerlendirilmelidir. Scope'lar açık olmalıdır. Swagger UI test yapılandırması production politikasıyla uyumlu olmalıdır.

Client Credentials

Client Credentials servisler arası kullanımda yaygındır. Kullanıcı etkileşimi gerektirmez. Client secret güvenli yerde tutulmalıdır. Browser tabanlı public UI içinde paylaşılmamalıdır. Scope ve token URL dokümante edilmelidir.

Scopes

Scope yetki kapsamını ifade eder. İsimler anlamlı olmalıdır. Çok geniş scope kullanımından kaçınılmalıdır. Operation hangi scope'u gerektiriyorsa belirtilmelidir. Scope değişiklikleri consumer etkisi yaratabilir.

Authorization URL

Authorization URL kullanıcının yönlendirildiği adres olabilir. Doğru ortam adresi kullanılmalıdır. Staging ve production ayrılmalıdır. Internal hostname public spec'e yazılmamalıdır. HTTPS kullanımı zorunlu kabul edilmelidir.

Token URL

Token URL credential'ın token'a dönüştürüldüğü endpoint'tir. Ortama göre doğru adres verilmelidir. Gerçek credential içermez. Client Credentials gibi flow'larda kritik bilgidir. Availability ve security kontrolleri ayrıca yapılmalıdır.

Swagger UI OAuth Yapılandırması

Swagger UI OAuth entegrasyonu test deneyimini kolaylaştırabilir. Redirect URL doğru yapılandırılmalıdır. Scope seçimi sınırlandırılmalıdır. Public browser içine secret konulmamalıdır. Production API için Try It Out politikası ayrıca değerlendirilmelidir.

Production Credential'larını Dokümana Yazmamak

Gerçek credential hiçbir dokümanda örnek veri olmamalıdır. Repository history içinden tamamen silmek zor olabilir. Secret scanner kullanılmalıdır. Example değerleri açıkça sahte olmalıdır. Credential sızıntısı durumunda rotation hemen yapılmalıdır.

Swagger UI Nedir?

Swagger UI, OpenAPI specification'ını geliştiricinin okuyabileceği ve uygun koşullarda etkileşime girebileceği web arayüzüne dönüştürür. Endpoint grupları, schema yapıları ve response modelleri tek yerde görülebilir. Try It Out özelliği doğru yapılandırıldığında öğrenme süresini kısaltır. Buna rağmen Swagger UI tek başına developer guide veya tutorial yerine geçmez. En güçlü kullanım biçimi, canonical OpenAPI contract'ın görsel reference katmanı olmasıdır.

OpenAPI Spec'i Görselleştirme

Swagger UI spec verisini okunabilir arayüze dönüştürür. Paths ve operations listelenir. Schema modelleri açılabilir. Description alanları gösterilir. Bu nedenle spec kalitesi doğrudan UI kalitesine yansır.

Endpoint Grupları

Tags endpoint'leri gruplar. Büyük API'lerde gezinme kolaylaşır. Tag standardı burada görünür hale gelir. Anlamsız gruplar kullanıcıyı yorar. Resource veya domain yaklaşımı tercih edilebilir.

Model Schema'ları

Schema modelleri request ve response yapısını gösterir. Required alanlar görülebilir. Enum değerleri listelenir. Description geliştiriciyi yönlendirir. Kötü schema tasarımı UI'da hemen fark edilir.

Request Builder

Request builder parametre girilmesini kolaylaştırır. Path ve query alanları ayrılır. Request body hazırlanabilir. Authentication bilgisi uygulanabilir. Production kullanımında yazma operation'larına dikkat edilmelidir.

Try It Out

Try It Out gerçek request gönderebilir. Öğrenme için faydalıdır. Staging üzerinde kullanılması daha güvenli olabilir. Production write operasyonlarında risk yaratabilir. Access policy ile birlikte düşünülmelidir.

Authentication

Swagger UI security scheme bilgilerini kullanabilir. Authorize arayüzü sağlayabilir. Bearer veya OAuth akışları desteklenebilir. Credential browser içinde işlendiği için güvenlik önemlidir. Public dokümanla internal authentication ayrılmalıdır.

Response Preview

Gönderilen request'in response'u ekranda görülebilir. Status code anlaşılır hale gelir. Headers incelenebilir. Error debugging kolaylaşır. Hassas response verileri için erişim kontrolü uygulanmalıdır.

Swagger UI Nasıl Kurulur?

Swagger UI farklı dağıtım modelleriyle kullanılabilir. Static hosting, container veya backend framework entegrasyonu seçenekleri vardır. Temel ihtiyaç, doğru OpenAPI URL'sini arayüze vermektir. Kurulumdan sonra yalnız görünümü değil, erişim güvenliğini ve ortam ayrımını da yapılandırmak gerekir. Production deployment için CORS, authentication ve Try It Out politikaları özellikle gözden geçirilmelidir.

Hosted Swagger UI

Hosted çözüm hızlı başlangıç sağlayabilir. Spec URL üzerinden yüklenebilir. Erişim politikasına dikkat edilmelidir. Internal API dış servise gönderilmemelidir. Kurum güvenlik kuralları belirleyici olmalıdır.

Static Hosting

Swagger UI static dosyalar olarak yayınlanabilir. CDN veya web server kullanılabilir. Deployment basittir. OpenAPI URL yapılandırması gereklidir. Access control ayrıca uygulanmalıdır.

Docker ile Swagger UI

Container ile Swagger UI izole biçimde çalıştırılabilir. OpenAPI URL environment değişkeniyle verilebilir. Deployment pipeline'a kolay eklenir. Image sürümü pinlenmelidir. Güncellemeler kontrollü yapılmalıdır.

Backend Framework ile Entegrasyon

Birçok backend framework OpenAPI ve UI entegrasyonu sunar. Code-first projelerde spec otomatik üretilebilir. Endpoint path yapılandırılabilir. Production erişimi kısıtlanabilir. Generated spec version control ve CI ile kontrol edilmelidir.

OpenAPI URL'sini Belirtmek

UI canonical specification adresini bilmelidir. Ortama göre URL değişebilir. Public ve internal spec ayrılabilir. Cache davranışı dikkate alınmalıdır. Yanlış spec gösterimi ciddi dokümantasyon hatasıdır.

Custom Configuration

Swagger UI davranışı çeşitli ayarlarla özelleştirilebilir. Expansion seviyesi değiştirilebilir. Request duration gösterilebilir. Try It Out davranışı sınırlandırılabilir. Özelleştirme standardı gölgelememelidir.

Swagger UI Özelleştirme

Swagger UI marka görünümüne uyarlanabilir, fakat görsel değişiklikler API standardizasyonuyla karıştırılmamalıdır. Logo ve tema kullanıcı deneyimini etkiler. Endpoint filtering ve default expansion daha büyük dokümanlarda gezinmeyi kolaylaştırabilir. Try It Out ayarları güvenlik modeline göre yapılandırılmalıdır. Öncelik her zaman doğru ve güncel OpenAPI contract olmalıdır.

Logo

Logo kurumsal görünüm sağlayabilir. API davranışını değiştirmez. Erişilebilirlik dikkate alınmalıdır. Aşırı görsel yük eklenmemelidir. Documentation portal ile uyumlu kullanılabilir.

Tema

Tema okunabilirliği iyileştirebilir. Renk kontrastı önemlidir. Dark mode tercih edilebilir. Upgrade sırasında custom tema test edilmelidir. İçerik görünümden daha önceliklidir.

CSS

CSS daha ayrıntılı görünüm değişikliği sağlar. Upgrade uyumluluğu göz önünde tutulmalıdır. Selector yapısına aşırı bağımlılık risklidir. Erişilebilirlik bozulmamalıdır. Custom kod minimumda tutulmalıdır.

Default Expansion

Expansion ayarı endpoint'lerin başlangıç görünümünü belirler. Büyük spec'te hepsini açık göstermek yorucu olabilir. Tag seviyesinde kapalı görünüm tercih edilebilir. Kullanıcı hızlı arama yapabilmelidir. Doküman büyüklüğüne göre karar verilmelidir.

Endpoint Filtering

Filtering aranan operation'ı bulmayı kolaylaştırır. Büyük API'lerde değerlidir. Tag standardıyla birlikte iyi çalışır. Güvenlik yöntemi değildir. Internal endpoint'i sadece gizlemek yeterli koruma sağlamaz.

Try It Out Ayarları

Try It Out güçlü fakat kontrollü kullanılmalıdır. Production write işlemleri sınırlanabilir. Staging varsayılan server yapılabilir. Authentication gereksinimi uygulanmalıdır. Audit ihtiyacı değerlendirilmelidir.

Branding ile Standardizasyon Arasındaki Fark

Branding görünümle ilgilidir. Standardizasyon contract davranışıyla ilgilidir. Güzel UI kötü spec'i düzeltmez. Önce naming, errors ve security standardı çözülmelidir. Görsel düzen bunun üzerine eklenmelidir.

Swagger UI Production Ortamında Güvenli mi?

Swagger UI'yi production ortamında yayınlamak tek başına güvenli veya güvensiz olarak sınıflandırılamaz. Risk, hangi specification'ın gösterildiğine, Try It Out erişimine ve authentication modeline bağlıdır. Internal endpoint veya hassas schema bilgileri public UI üzerinden sızdırılmamalıdır. Production'a yazma request'i gönderebilen bir arayüz yetkilendirme olmadan bırakılmamalıdır. Çoğu ekip için staging üzerinde etkileşim, production üzerinde kontrollü reference yaklaşımı daha güvenli bir başlangıçtır.

Public ve Internal API Ayrımı

Public ve internal endpoint'ler ayrı değerlendirilmelidir. Aynı spec içinde bulunmaları bilgi sızıntısı yaratabilir. Build sırasında iki çıktı üretilebilir. Internal UI VPN arkasında tutulabilir. Access policy açıkça tanımlanmalıdır.

Internal Endpoint Sızıntısı

Internal hostname saldırı yüzeyi hakkında bilgi verebilir. Gizli admin endpoint'leri public spec'te görünmemelidir. Sadece UI'da CSS ile saklamak güvenlik sağlamaz. Spec üretim aşamasında filtrelenmelidir. Security review bunu kontrol etmelidir.

Try It Out Riskleri

Try It Out gerçek API request'i gönderebilir. Yanlışlıkla veri değişikliği yapılabilir. Credential browser oturumunda bulunabilir. Production kullanımında rol kontrolü gerekir. Read-only reference modu düşünülebilir.

Production'a Yazma İsteği Gönderme Riski

POST ve DELETE operation'ları gerçek etki yaratabilir. Test amacıyla production üzerinde kullanılmamalıdır. Staging server varsayılan yapılabilir. Production write erişimi ayrıca sınırlandırılabilir. Audit log tutulması faydalıdır.

Swagger UI Authentication

UI erişiminin kendisi authentication arkasında olabilir. Bu, API authentication'dan ayrı bir katmandır. SSO kullanılabilir. Role-based erişim uygulanabilir. Internal doküman public internete açık bırakılmamalıdır.

IP/VPN Kısıtlaması

Internal UI VPN arkasında tutulabilir. IP allow list ek koruma sağlayabilir. Tek başına yeterli güvenlik değildir. Authentication ile birlikte kullanılmalıdır. Remote çalışma ihtiyaçları dikkate alınmalıdır.

Staging API Üzerinde Try It Out

Staging deneme için daha güvenli ortamdır. Test verileri kullanılabilir. Production etkisi oluşmaz. Authentication akışı yine gerçekçi tutulabilir. CORS politikası kontrollü biçimde yapılandırılmalıdır.

Hassas Schema ve Example'ları Gizlemek

Hassas veri example içine konulmamalıdır. Secret alanları hiçbir zaman gerçek değer göstermemelidir. Internal field public schema'dan çıkarılabilir. Sanitization build sürecine eklenebilir. Review checklist bunu kontrol etmelidir.

API-First Nedir?

API-first yaklaşımında API contract uygulama kodundan önce tasarım sürecinin merkezine alınır. Frontend, mobile ve backend ekipleri aynı sözleşme üzerinde uzlaşabilir. Mock server sayesinde consumer ekipler implementasyon tamamlanmadan çalışmaya başlayabilir. Erken review naming, security ve response modelindeki sorunların kod yazılmadan görülmesini sağlar. Özellikle çok ekipli projelerde bu yaklaşım iletişim maliyetini düşürebilir.

Önce Contract

İlk olarak API davranışı tanımlanır. Endpoint ve schema üzerinde uzlaşılır. OpenAPI dosyası review edilir. Business senaryosu örneklerle doğrulanır. Kod daha sonra contract'a göre geliştirilir.

Sonra Implementation

Contract onaylandıktan sonra implementation başlar. Backend sözleşmeyi uygular. Consumer ekip aynı contract'a göre ilerler. Değişiklik gerektiğinde spec önce güncellenebilir. Drift kontrolü pipeline'da yapılmalıdır.

Frontend ve Backend'in Paralel Çalışması

Mock API frontend'in bekleme süresini azaltır. Type üretimi spec'ten yapılabilir. Backend bağımsız geliştirilir. Integration aşamasında sürpriz azalır. Contract ortak koordinasyon noktası olur.

Mock Server

Mock server examples üzerinden response üretebilir. Consumer gerçek endpoint'i beklemez. Edge case örnekleri eklenebilir. Contract review daha somut hale gelir. Mock ile production davranışı arasında fark kalmaması için test gerekir.

Erken API Review

API review tasarım aşamasında yapılmalıdır. Naming ve status code hataları erkenden bulunur. Security gereksinimleri incelenir. Consumer geri bildirimi alınır. Değişiklik maliyeti kod sonrasına göre daha düşüktür.

Breaking Change'leri Daha Kod Yazılmadan Yakalamak

Contract diff tasarım değişikliğini gösterebilir. Required parametre ekleme erken fark edilir. Response field kaldırma görünür olur. Consumer etkisi değerlendirilir. Gerekirse versioning kararı koddan önce alınır.

Design-First API Development

Design-first yaklaşımında OpenAPI dosyası geliştirme başlamadan önce tasarlanır. Swagger Editor gibi araçlar yazım ve görsel kontrol sürecini kolaylaştırabilir. Tasarım review sonrasında mock API veya server stub üretilebilir. Bu model özellikle public API, partner entegrasyonu ve çok ekipli projelerde değer sağlar. Yine de spec'in gerçek implementasyondan kopmaması için CI içinde drift kontrolleri kurulmalıdır.

OpenAPI Dosyasını Önce Tasarlamak

İlk çıktı executable code değil contract olur. Domain modeli düşünülür. Endpoint davranışı örneklenir. Consumer ekip review yapar. Implementation onaylanan spec'e göre başlar.

Swagger Editor

Swagger Editor yazım sırasında geri bildirim sağlar. Syntax hataları erken görülebilir. Preview tasarımı görselleştirir. Ekip review için spec paylaşabilir. Kurumsal ruleset ayrıca uygulanmalıdır.

API Review

Review yalnız backend ekibi tarafından yapılmamalıdır. Consumer temsilcisi katılmalıdır. Security gereksinimleri incelenmelidir. Naming ve lifecycle etkisi değerlendirilmelidir. Kararlar pull request içinde kaydedilebilir.

Mock API

Mock API contract'ın kullanılabilirliğini test eder. Frontend ilk request'i gönderir. Example kalitesi ortaya çıkar. Eksik field'ler erken fark edilir. Tasarım iyileştirmesi implementation öncesinde yapılabilir.

Server Stub

Server stub operation imzalarını oluşturabilir. Geliştirici business logic ekler. Contract yapısı başlangıçtan korunur. Generated kod doğrudan production kalitesi kabul edilmemelidir. Architecture standardına adapte edilmelidir.

Implementation

Implementation onaylanan contract'ı gerçekleştirmelidir. Runtime validation kullanılabilir. Contract testleri eklenmelidir. Spec değişirse review tekrarlanmalıdır. Deployment öncesi diff kontrolü yapılmalıdır.

Code-First API Documentation

Code-first yaklaşımında OpenAPI specification uygulama kodundaki annotation, decorator veya type metadata üzerinden üretilir. Framework entegrasyonu güçlü olduğunda hızlı ve kullanışlı olabilir. En büyük risk, generated specification'ın kimse tarafından review edilmemesidir. Üretilen dosya CI içinde lint edilmeli ve mümkünse version control üzerinden değişiklik farkı izlenmelidir. Code-first kullanmak API style guide gereksinimini ortadan kaldırmaz.

Koddan OpenAPI Üretmek

Framework route bilgilerini okuyabilir. Schema type'lardan çıkarılabilir. Specification otomatik oluşturulur. Manuel tekrar azalır. Generated çıktının doğruluğu yine kontrol edilmelidir.

Annotation

Annotation metadata'yı kod üzerinde tanımlar. Java ekosisteminde sık görülür. Description ve response bilgileri eklenebilir. Fazla annotation okunabilirliği azaltabilir. Ortak convention belirlenmelidir.

Decorator

Decorator TypeScript ve benzeri ekosistemlerde kullanılabilir. Route ve schema metadata'sı ekler. Kodla doküman yakın kalır. Eksik decorator eksik spec üretir. CI coverage kontrolü faydalıdır.

Type Metadata

Type metadata schema üretimini kolaylaştırır. Required ve optional alanlar çıkarılabilir. Runtime validation ile compile-time type farklı olabilir. Bu fark kontrol edilmelidir. Generated schema contract testiyle doğrulanmalıdır.

Framework Entegrasyonu

Framework entegrasyonu hızlı başlangıç sağlar. Swagger UI otomatik açılabilir. OpenAPI endpoint'i üretilebilir. Production ayarı kontrol edilmelidir. Framework upgrade spec değişikliğine neden olabilir.

Generated Spec'i Versiyon Kontrolüne Almak

Generated spec version control'e alınabilir. Pull request diff görünür hale gelir. Breaking change detection çalıştırılabilir. Deterministik çıktı gereklidir. Gereksiz ordering farkları azaltılmalıdır.

Design-First vs Code-First

Design-first ve code-first arasında tek bir doğru seçim yoktur. Yeni public API'lerde consumer review gereksinimi nedeniyle design-first güçlü olabilir. Legacy servislerde mevcut koddan spec çıkarmak daha gerçekçi bir başlangıçtır. Küçük ekipler code-first ile hızlı ilerleyebilir, büyük organizasyonlar ise merkezi review gerektirebilir. Önemli olan hangi yaklaşım seçilirse seçilsin canonical contract ve drift kontrolünün açık biçimde tanımlanmasıdır.

Yeni API

Yeni API'de tasarım özgürlüğü yüksektir. Design-first uygulanabilir. Consumer geri bildirimi erken alınır. Style guide baştan uygulanır. Teknik borç daha başlamadan azaltılabilir.

Legacy API

Legacy API'de önce mevcut davranış keşfedilmelidir. Code-first spec üretimi başlangıç olabilir. Gerçek response'lar contract ile karşılaştırılmalıdır. Sonra standardizasyon kademeli yapılabilir. Bir anda breaking redesign yapılmamalıdır.

Internal API

Internal API de contract disiplinine ihtiyaç duyar. Tüketiciler aynı kurum içinde olsa bile bağımlılık vardır. Hızlı değişiklik breaking etki yaratabilir. Basit governance yeterli olabilir. Ownership mutlaka tanımlanmalıdır.

Public API

Public API daha güçlü backward compatibility gerektirir. Design-first review faydalıdır. Changelog ve deprecation politikası şarttır. Örnekler daha kapsamlı olmalıdır. Breaking change approval süreci kurulmalıdır.

Büyük Organizasyon

Büyük organizasyonda ekip çeşitliliği artar. Ortak style guide gerekir. Merkezi ruleset otomasyonu önem kazanır. API catalog ownership bilgisini toplar. Manual approval tek başına ölçeklenmez.

Küçük Ekip

Küçük ekip daha hafif süreç kullanabilir. Code-first pratik olabilir. Yine de naming ve error standardı belirlenmelidir. CI lint kolayca eklenebilir. Küçük başlamak ileride geçiş maliyetini azaltır.

Hangi Yaklaşım Ne Zaman Kullanılmalı?

Karar ekip yapısına göre verilmelidir. Public contract varsa design-first avantajlıdır. Mevcut kod ağır basıyorsa code-first daha hızlı olabilir. Hibrit model de mümkündür. En önemli kriter spec ile runtime arasındaki uyumdur.

Contract-First Yaklaşımı

Contract-first yaklaşımında OpenAPI dosyası consumer ve provider arasındaki resmi teknik sözleşme olarak değerlendirilir. Değişiklik yalnız backend'in iç kararı olmaktan çıkar. Consumer etkisi review edilir ve contract testleriyle doğrulanır. Spec drift tespit edildiğinde pipeline deployment'ı durdurabilir. Bu yaklaşım API dokümantasyonunu yaşayan mühendislik varlığına dönüştürür.

OpenAPI'nin Sözleşme Olması

Spec beklenen davranışı açıkça tanımlar. Provider bunu uygulamayı taahhüt eder. Consumer buna göre entegrasyon geliştirir. Değişiklik kayıt altında yapılır. Contract yalnız açıklama metni olarak görülmez.

Consumer ve Provider

Provider API'yi sunan taraftır. Consumer API'yi kullanır. İki taraf farklı ekip olabilir. Contract ortak iletişim katmanıdır. Review iki tarafın beklentisini buluşturur.

Contract Review

Contract review değişiklik etkisini inceler. Naming ve schema değerlendirilir. Security gereksinimi kontrol edilir. Consumer compatibility düşünülür. Kararlar repository içinde kayıt altına alınabilir.

Contract Testing

Test gerçek davranışı sözleşmeyle karşılaştırır. Response schema doğrulanır. Request validation kontrol edilir. Status code farkları yakalanır. Deployment güveni artar.

Spec Drift

Spec drift doküman ile gerçek API'nin ayrışmasıdır. Manuel dokümantasyonda sık görülür. Runtime test bunu fark edebilir. Code-first generation da çözüm sağlayabilir. Drift kabul edilmeden düzeltilmelidir.

Contract'ın Deployment Gate Olması

Contract kontrolleri deployment öncesi çalıştırılabilir. Breaking change tespitinde build durabilir. Lint error merge'i engelleyebilir. Contract test failure release'i durdurabilir. Governance otomatik hale gelir.

OpenAPI Specification ile Kod Nasıl Senkron Tutulur?

Spec ile kodu senkron tutmanın tek bir yöntemi yoktur. Spec'ten kod üretilebilir veya koddan specification çıkarılabilir. Her iki yaklaşımda da hangi dosyanın golden source olduğu açıkça belirlenmelidir. CI içinde önceki ve yeni specification karşılaştırılmalı, runtime contract testleriyle gerçek davranış doğrulanmalıdır. Drift görüldüğünde pipeline'ın başarısız olması dokümanın güncelliğini koruyan en güçlü önlemlerden biridir.

Spec'ten Kod Üretme

Design-first projelerde spec input olabilir. Server interface üretilebilir. Client SDK aynı kaynaktan çıkabilir. Generated kod kontrollü kullanılmalıdır. Contract değişikliği generation sürecini tetikler.

Koddan Spec Üretme

Code-first projelerde framework specification üretir. Type metadata kullanılır. CI çıktıyı kaydedebilir. Diff review yapılır. Runtime davranışın generated spec ile eşleştiği test edilmelidir.

Golden OpenAPI File

Golden file canonical contract'tır. Diğer çıktılar buradan türetilir. Değişiklik yalnız kontrollü süreçle yapılır. Repository içinde versiyonlanır. Hangi dosyanın golden olduğu herkesçe bilinmelidir.

CI'da Spec Comparison

CI önceki spec ile yeni spec'i karşılaştırabilir. Structural diff çıkarılır. Breaking change sınıflandırılır. Review bilgisi üretilir. Onaysız kırıcı değişiklik merge edilmez.

Runtime Contract Tests

Runtime test gerçek endpoint'i çağırır. Response spec'e göre validate edilir. Header ve status code kontrol edilir. Drift bulunur. Staging ortamında düzenli çalıştırılabilir.

Drift Tespitinde Pipeline'ı Durdurmak

Drift warning olarak bırakılırsa zamanla normalleşebilir. Kritik farklarda build fail etmek daha etkilidir. İstisna approval süreci olabilir. Sorun düzeltilmeden production'a çıkılmamalıdır. Bu politika ekip tarafından önceden bilinmelidir.

API Dokümantasyonu için Single Source of Truth

Single Source of Truth yaklaşımı aynı bilginin farklı yerlerde manuel olarak tekrar edilmesini önler. Canonical OpenAPI specification repository içinde tutulabilir. Swagger UI, developer portal reference, mock server ve SDK aynı spec'ten üretilebilir. Böylece endpoint değişikliğinde beş farklı dokümanı elle güncellemek gerekmez. API Dokümantasyonunda Swagger Kullanımı ve Standardizasyon açısından en güçlü kazanımlardan biri tam olarak bu otomasyon modelidir.

Canonical OpenAPI Specification

Canonical spec resmi API contract'tır. Diğer çıktılar ona dayanır. Sürümü kontrol edilir. Review sürecinden geçer. Kimse farklı bir kopyayı gerçek kaynak olarak kullanmamalıdır.

Git Repository

Git değişiklik tarihçesini tutar. Pull request review sağlar. Branch politikası uygulanabilir. Rollback mümkündür. Docs-as-code yaklaşımının temelidir.

Swagger UI

Swagger UI canonical spec'i görselleştirir. Manuel endpoint listesi tutmaz. Deployment spec değişiminde güncellenir. Cache kontrol edilmelidir. Gösterilen sürüm açık olmalıdır.

Developer Portal

Portal reference yanında guide sunar. Getting Started içeriği barındırır. SDK bağlantıları verilebilir. Changelog ve support bilgisi eklenebilir. Reference yine canonical spec'ten üretilmelidir.

SDK

SDK generator spec'i input olarak kullanabilir. operationId method isimlerini etkiler. Release version API lifecycle ile eşlenebilir. Integration test gerekir. Manuel patch'ten kaçınılmalıdır.

Mock Server

Mock server contract üzerinden response üretebilir. Example verileri kullanır. Frontend geliştirmesini hızlandırır. Spec değişince mock güncellenir. Ayrı manuel mock contract'ı tutulmamalıdır.

Testler

Testler schema ve examples üzerinden türetilebilir. Contract validation uygulanabilir. Negatif senaryolar üretilebilir. Runtime cevaplar kontrol edilir. Dokümantasyon test edilebilir varlığa dönüşür.

Hepsinin Aynı Spec'ten Üretilmesi

Tek kaynak drift riskini azaltır. Doküman ve SDK aynı contract'ı görür. Mock davranışı uyumlu kalır. CI değişikliği merkezi izler. Ekip güveni artar.

Kurumsal API Standardizasyonu Nedir?

Kurumsal API standardizasyonu farklı ekiplerin API tasarlarken ortak karar setini kullanmasıdır. Bu yaklaşım tüm API'lerin birebir aynı olması anlamına gelmez. Naming, error model, pagination, authentication ve versioning gibi yatay konularda ortak davranış oluşturulur. Style guide kararları machine-readable lint kurallarına dönüştürüldüğünde uygulama daha sürdürülebilir hale gelir. Developer Experience standardı da teknik governance'ın önemli bir sonucu olur.

Her Ekibin Farklı API Tasarlamasının Sorunları

Farklı tasarım consumer öğrenme maliyetini artırır. Aynı hata farklı formatta döner. Pagination parametreleri değişir. Authentication akışları ayrışır. Ortak SDK geliştirmek zorlaşır.

API Style Guide

Style guide tasarım kararlarını yazılı hale getirir. Naming kuralları içerir. Status code politikası açıklar. Example ve security beklentisini tanımlar. Otomatik uygulanabilen kurallar ruleset'e dönüştürülmelidir.

Governance

Governance standardın uygulanmasını sağlar. Yalnız merkezi kurul anlamına gelmez. Otomatik guardrail tercih edilebilir. Review ve tooling birlikte çalışır. Developer hızını gereksiz yere düşürmemelidir.

Reusable Components

Ortak component standardı somutlaştırır. Error schema paylaşılabilir. Pagination modeli reuse edilebilir. Security scheme aynı kalır. Versiyonlama politikası gerekir.

Automated Enforcement

Otomasyon kuralların unutulmasını önler. Linter pull request sırasında çalışır. Breaking diff pipeline'da kontrol edilir. Error seviyesinde build durabilir. Manual review daha anlamlı konulara odaklanır.

Developer Experience Standardı

DX de ölçülebilir standardın parçasıdır. İlk başarılı request süresi izlenebilir. Example coverage ölçülebilir. Error açıklamaları kontrol edilebilir. API kalitesi yalnız server performansıyla değerlendirilmez.

API Style Guide Nasıl Oluşturulur?

Style guide oluştururken yüzlerce kural yazarak başlamak yerine en sık tekrarlanan tasarım kararlarına odaklanmak daha verimlidir. Naming, URI, HTTP methods, status codes, error model, pagination ve authentication iyi bir başlangıç setidir. Her kuralın gerekçesi ve olumlu örneği bulunmalıdır. Otomatik doğrulanabilen kurallar ayrıca işaretlenmelidir. Style guide yaşayan bir doküman olmalı ve değişiklikleri RFC benzeri süreçle yönetilmelidir.

Naming

Naming endpoint ve field isimlerini kapsar. Convention açık olmalıdır. Acronym kullanımı tanımlanmalıdır. Domain sözlüğü eklenebilir. Linter bazı kuralları otomatik kontrol edebilir.

URI Design

URI resource odaklı tasarlanmalıdır. Çoğul kullanım standardize edilebilir. Nesting sınırı belirlenmelidir. Case convention açıklanmalıdır. Örnekler gerçekçi olmalıdır.

HTTP Methods

Method semantiği standart olmalıdır. GET read için kullanılır. POST create veya action için kontrollü kullanılır. PUT ve PATCH farkı açıklanmalıdır. DELETE davranışı belirlenmelidir.

HTTP Status Codes

Status code karar tablosu hazırlanmalıdır. Validation hatası için ortak politika olmalıdır. Conflict davranışı netleştirilmelidir. Async operation için 202 açıklanabilir. Error model tüm kodlarla uyumlu olmalıdır.

Error Model

Ortak error schema zorunlu olmalıdır. Machine code kullanılmalıdır. Correlation ID eklenebilir. Field errors standardize edilmelidir. Documentation link politikası tanımlanabilir.

Pagination

Pagination parametreleri standart olmalıdır. Cursor veya page yaklaşımı seçilmelidir. Limit sınırları tanımlanmalıdır. Metadata modeli ortak olmalıdır. İstisna koşulları belgelenmelidir.

Filtering

Filter naming standardı belirlenmelidir. Çoklu değer semantiği açıklanmalıdır. Unsupported field davranışı tanımlanmalıdır. Date range convention eklenebilir. Security açısından field exposure kontrol edilmelidir.

Sorting

Sort parametre adı standart olmalıdır. Direction değerleri belirlenmelidir. Default order yazılmalıdır. Desteklenen alanlar listelenmelidir. Stable sorting ihtiyacı değerlendirilmelidir.

Authentication

Security scheme standardı belirlenmelidir. Bearer ve OAuth kullanım kuralları açıklanmalıdır. Scope naming yazılmalıdır. Credential güvenliği vurgulanmalıdır. Public endpoint istisnaları tanımlanmalıdır.

Versioning

API versioning modeli kurum genelinde belirlenmelidir. URI veya header yaklaşımı seçilebilir. Breaking change tetikleyicileri tanımlanmalıdır. API version ile OpenAPI version ayrılmalıdır. Migration rehberi zorunlu hale getirilebilir.

Deprecation

Deprecation policy yaşam döngüsünü yönetir. Tarih belirtilmelidir. Sunset süresi tanımlanmalıdır. Consumer bildirim kanalı açıklanmalıdır. Migration guide bağlantısı verilmelidir.

API Style Guide'da Hangi Kurallar Zorunlu Olmalı?

Zorunlu kurallar ekiplerin sürekli hata yaptığı ve consumer üzerinde doğrudan etkisi olan konulardan seçilmelidir. Her operation için operationId, summary ve tag bulunması temel kaliteyi artırır. Security scheme, standard error response ve pagination kuralları da ortak deneyim sağlar. API owner ve contact bilgisinin zorunlu olması operasyonel sahipliği görünür hale getirir. Example zorunluluğu ise hem insan okuyucu hem mock ve test süreçleri için büyük değer üretir.

Her Operation'da operationId

operationId tooling için değerlidir. SDK isimlerini etkiler. Benzersiz olmalıdır. Naming convention izlemelidir. Linter bunu zorunlu kılabilir.

Her Operation'da summary

Summary hızlı gezinme sağlar. Kısa olmalıdır. Operation amacını anlatmalıdır. UI'da görünür. Empty summary lint hatası yapılabilir.

Description Zorunluluğu

Description kritik davranışı açıklamalıdır. Her trivial operation için uzun metin gerekmez. Kurum minimum beklenti belirleyebilir. Business kısıtlar eklenebilir. Kalite yalnız varlık kontrolüyle ölçülmemelidir.

Tag Zorunluluğu

Tag bilgi mimarisi sağlar. Her operation en az bir anlamlı grupta olmalıdır. İzin verilen tag listesi kullanılabilir. Spelling farkları engellenmelidir. Çoklu tag sınırı belirlenebilir.

Security Scheme

Security requirements açık olmalıdır. Protected operation scheme kullanmalıdır. Public operation bilinçli işaretlenmelidir. Secret spec'e yazılmamalıdır. Linter eksik tanımı bulabilir.

Standard Error Responses

Ortak hatalar tüm operation'larda bulunmalıdır. Error schema merkezi olmalıdır. Status code politikası izlenmelidir. Correlation ID kullanılabilir. Contract test gerçek response'u doğrulamalıdır.

Standard Pagination

Liste endpoint'leri aynı pagination modelini kullanmalıdır. Parametre isimleri ortak olmalıdır. Response metadata paylaşılmalıdır. İstisnalar review gerektirebilir. SDK helper bu standardı kullanabilir.

Contact ve API Owner

Her API'nin sahibi bulunmalıdır. Support kanalı aktif olmalıdır. Metadata catalog ile senkron tutulmalıdır. Bireysel çalışan hesabına bağımlılık azaltılmalıdır. Eksik owner deployment uyarısı oluşturabilir.

Example Zorunluluğu

Request ve response example geliştirici deneyimini iyileştirir. Mock server kalitesi artar. PII kullanılmamalıdır. Schema ile uyum test edilmelidir. Example coverage scorecard içinde ölçülebilir.

API Guidelines ile Style Guide Arasındaki Fark

Guideline ile enforceable rule aynı ağırlığa sahip değildir. Bazı öneriler mimari bağlama göre değişebilir, bazı kurallar ise kurum genelinde zorunlu olabilir. Style guide içinde error, warning ve recommendation seviyelerini ayırmak ekiplerin beklentiyi anlamasını kolaylaştırır. Linter tarafından kontrol edilemeyen kurallar review checklist içinde tutulabilir. Bu ayrım governance'ın daha adil ve uygulanabilir olmasını sağlar.

Guideline

Guideline iyi uygulamayı açıklar. Her durumda zorunlu olmayabilir. Gerekçe sunar. Tasarım kararına rehberlik eder. İhlal için manuel değerlendirme yapılabilir.

Recommendation

Recommendation tercih edilen yaklaşımı gösterir. Alternatif kabul edilebilir olabilir. Neden tercih edildiği yazılmalıdır. Warning seviyesine bağlanabilir. Ekip bağlama göre karar verebilir.

Enforceable Rule

Enforceable rule açık ve ölçülebilir olmalıdır. operationId zorunluluğu buna örnektir. CI içinde kontrol edilebilir. İhlal build'i durdurabilir. Exception süreci tanımlanmalıdır.

Lint Rule

Lint rule specification üzerinde otomatik kontrol yapar. JSONPath benzeri selector kullanabilir. Naming kontrol edilebilir. Required metadata bulunabilir. Merkezi ruleset içinde versionlanmalıdır.

Error vs Warning

Error merge'i engelleyebilir. Warning geliştiriciyi bilgilendirir. Severity risk seviyesine göre seçilmelidir. Her şeyi error yapmak verimsizdir. Ekip güveni korunmalıdır.

Otomatikleştirilemeyen Mimari Kurallar

Bazı kararlar bağlam gerektirir. Resource boundary buna örnektir. Linter bunu tam anlayamayabilir. Architecture review kullanılabilir. Checklists otomasyonu tamamlayan araç olmalıdır.

Spectral Nedir?

Spectral, OpenAPI gibi yapılandırılmış API tanımlarına lint kuralları uygulamak için kullanılan bir araçtır. Built-in kurallar yanında kuruma özel ruleset hazırlanabilir. JSONPath tabanlı seçimlerle operationId, tags, contact veya custom extension alanları kontrol edilebilir. Severity seviyeleri ekiplerin hangi ihlalin build'i durduracağını belirlemesine yardımcı olur. En güçlü kullanım biçimi API style guide kararlarını policy as code yaklaşımına dönüştürmektir.

OpenAPI Linter

Linter specification'ı statik olarak analiz eder. Hatalı pattern'leri bulur. Style guide uyumunu ölçer. IDE ve CI içinde çalışabilir. Manual review yükünü azaltır.

Built-in OpenAPI Rules

Hazır kurallar hızlı başlangıç sağlar. Yaygın specification sorunlarını bulabilir. Kurum ihtiyaçlarının tamamını kapsamayabilir. Custom kurallarla genişletilebilir. Tool version'ı pinlenmelidir.

Custom Ruleset

Custom ruleset kurum standardını kodlaştırır. Naming kontrolü eklenebilir. x-owner zorunlu yapılabilir. Error response kontrol edilebilir. Ruleset ayrı package olarak dağıtılabilir.

JSONPath

JSONPath belirli spec alanlarını seçmeye yardımcı olur. Rule hedefi tanımlanır. Operation veya schema üzerinde çalışabilir. Selector okunabilir tutulmalıdır. Test dosyalarıyla doğrulanmalıdır.

Severity

Severity ihlalin önemini gösterir. Her kural aynı ağırlıkta değildir. Kritik security kuralı error olabilir. Style tercihi warning olabilir. Seviye ekip tarafından belgelenmelidir.

Error

Error kritik ihlali temsil eder. CI build'i durdurabilir. Breaking security problemi buna örnek olabilir. False positive düşük olmalıdır. Exception kontrollü yapılmalıdır.

Warn

Warn geliştiriciyi uyarır. Merge'i zorunlu olarak engellemez. Geçiş döneminde faydalıdır. Teknik borç ölçülebilir. Zamanla error seviyesine yükseltilebilir.

Info

Info bilgilendirici geri bildirim sunar. Tasarım kalitesini iyileştirebilir. Build'i etkilemez. Eğitim amacı taşıyabilir. Gürültü yaratmaması önemlidir.

Hint

Hint hafif öneri sağlar. Geliştiriciyi yönlendirir. Kritik politika için kullanılmamalıdır. IDE deneyiminde faydalı olabilir. Sayısı kontrollü tutulmalıdır.

Kurumsal API Standardını Kod Haline Getirmek

Yazılı kural kolay unutulabilir. Ruleset otomatik kontrol sağlar. Aynı kontrol her repository'de çalışır. Sonuç ölçülebilir hale gelir. Governance ölçeklenebilir olur.

Spectral ile OpenAPI Standardizasyonu

Spectral ile kurumsal API standardizasyonu en fazla tekrar edilen kontrollerin otomatik hale getirilmesiyle başlar. operationId, naming, tag, contact ve server kuralları iyi adaylardır. Security scheme ve standard error response kontrolleri daha yüksek risk taşıdığı için error seviyesinde uygulanabilir. x-owner gibi kurum içi metadata alanları da zorunlu tutulabilir. Ruleset değişiklikleri normal kod gibi test edilmeli ve versionlanmalıdır.

operationId Kontrolü

Her operation'da operationId aranabilir. Pattern doğrulanabilir. Duplicate değerler bulunabilir. Naming convention uygulanabilir. SDK kalitesi korunur.

Naming Convention

Path ve field naming rule ile kontrol edilebilir. kebab-case zorunlu yapılabilir. operationId camelCase olabilir. İstisna listesi tutulabilir. Kural örneklerle test edilmelidir.

Tag Kontrolü

Tag varlığı kontrol edilir. İzin verilen tag listesi kullanılabilir. Boş description uyarılabilir. Fazla tag engellenebilir. UI organizasyonu daha tutarlı olur.

Contact Zorunluluğu

info.contact eksikliği lint error olabilir. Support kanalının bulunması sağlanır. Format kontrol edilebilir. x-owner ile birlikte değerlendirilebilir. API sahipsiz kalmaz.

Server Kontrolü

Production server formatı kontrol edilebilir. HTTP kullanımına izin verilmeyebilir. Internal hostname public spec'te engellenebilir. Environment policy uygulanabilir. Security review otomatikleşir.

Security Scheme Kontrolü

Protected API security scheme kullanmalıdır. Belirli scheme isimleri zorunlu olabilir. Query API key yasaklanabilir. Operation override kontrol edilebilir. Güvenlik standardı kod haline gelir.

Error Schema Kontrolü

4xx ve 5xx response'larda ortak schema aranabilir. $ref zorunlu yapılabilir. Correlation ID kontrol edilebilir. Description eksikliği uyarılabilir. Consumer deneyimi standardize edilir.

Custom x-owner Zorunluluğu

x-owner takım sahipliğini taşıyabilir. Linter alanı zorunlu kılar. Değer takım kataloğuyla karşılaştırılabilir. Catalog otomasyonu bu bilgiyi okuyabilir. Ownership değişikliği review edilir.

IDE İçinde OpenAPI Linting

Governance yalnız CI aşamasında çalışırsa geliştirici hatayı geç öğrenir. IDE linting aynı kuralı dosya yazılırken gösterebilir. Bu yaklaşım shift-left prensibini destekler. Kurum ruleset'i repository konfigürasyonuyla otomatik yüklenmelidir. Geliştiricinin ayrı ayar yapmasına gerek kalmadığında standardın benimsenmesi kolaylaşır.

Developer Yazarken Hata Gösterme

Erken feedback düzeltme maliyetini azaltır. operationId hatası anında görünür. Missing description fark edilir. CI sürprizi azalır. Geliştirici kuralı uygularken öğrenir.

VS Code

VS Code OpenAPI geliştirmede sık kullanılan editörlerden biridir. Extension desteği vardır. Lint feedback gösterilebilir. Repository ayarları paylaşılabilir. Ekip standardı kolaylaştırılabilir.

Spectral Extension

Spectral entegrasyonu editor içinde rule sonucu gösterebilir. Custom ruleset kullanılabilir. Severity renklerle görünür. CI ile aynı kurallar tercih edilmelidir. Böylece lokal ve pipeline sonucu ayrışmaz.

Kurum Ruleset'ini Otomatik Kullanmak

Ruleset package olarak dağıtılabilir. Repository config merkezi konumu işaret edebilir. Version pinlenebilir. Upgrade pull request ile yapılabilir. Her geliştiricinin manuel kopya tutması önlenir.

Shift-Left API Governance

Shift-left kontrolü geliştirme sürecinin başına taşır. Hatalar pull request'ten önce bulunur. Review daha stratejik konulara odaklanır. Developer autonomy korunur. Governance geciktiren kapı olmaktan çıkar.

CI/CD İçinde OpenAPI Linting

CI/CD linting kurumsal standardın herkes için aynı biçimde uygulanmasını sağlar. Pull request açıldığında syntax, style ve güvenlik kuralları otomatik kontrol edilebilir. Kritik error build'i durdururken warning rapora eklenebilir. Bu sonuçlar pull request üzerinde görünür olduğunda geliştirici hızlı düzeltme yapabilir. Local IDE linting ile aynı ruleset kullanmak tutarsız sonuçları azaltır.

Pull Request

Spec değişikliği pull request ile review edilir. Diff görünür olur. Automation çalışır. Consumer etkisi tartışılır. Approval kaydı saklanır.

Spectral Lint

Spectral lint ruleset'i uygular. Error ve warning üretir. Sonuç raporlanabilir. Exit code CI'ı kontrol eder. Ruleset version'ı loglanmalıdır.

Syntax Validation

Syntax validation belgenin parse edilebilir olduğunu doğrular. YAML hataları bulunur. OpenAPI temel yapısı kontrol edilir. Style lint'ten önce çalıştırılabilir. Geçersiz spec erken reddedilir.

Style Validation

Style validation kurum kurallarını kontrol eder. Naming buna örnektir. Summary zorunluluğu doğrulanabilir. Tag standardı uygulanır. Sonuç quality score'a aktarılabilir.

Security Rules

Security lint riskli tanımları bulabilir. HTTP server yasaklanabilir. Eksik security scheme tespit edilebilir. Internal hostname kontrol edilebilir. Gerçek secret scanning ayrıca yapılmalıdır.

Error'da Build Fail

Kritik ihlal merge edilmemelidir. CI non-zero exit verebilir. Error kuralları sınırlı ve güvenilir olmalıdır. Exception approval gerektiğinde kayıt altına alınmalıdır. False positive güveni azaltmamalıdır.

Warning'leri Raporlamak

Warning görünür tutulmalıdır. Dashboard içinde izlenebilir. Teknik borç eğilimi ölçülebilir. Hemen build durdurmak zorunda değildir. Zamanla kurallar sıkılaştırılabilir.

Breaking Change Nedir?

Breaking change mevcut consumer'ın aynı şekilde çalışmaya devam etmesini engelleyebilecek contract değişikliğidir. Endpoint silmek en açık örnektir, fakat required parameter eklemek veya response field tipini değiştirmek de kırıcı olabilir. operationId değişikliği HTTP davranışını değiştirmese bile generated SDK kullanıcılarını etkileyebilir. Breaking change tanımı kurum style guide içinde örneklerle açıklanmalıdır. Her spec değişikliği CI diff kontrolünden geçirilmelidir.

Endpoint Silmek

Endpoint kaldırmak doğrudan consumer'ı etkiler. Önce deprecation uygulanmalıdır. Migration alternatifi verilmelidir. Sunset tarihi duyurulmalıdır. Major version gerekebilir.

HTTP Method Değiştirmek

GET'i POST yapmak contract'ı değiştirir. Client kodu çalışmaz. Cache davranışı da değişir. Yeni endpoint veya version tercih edilebilir. Diff bunu kırıcı olarak işaretlemelidir.

Required Parameter Eklemek

Yeni required parametre eski client'ların request'ini geçersiz yapar. Bu nedenle breaking change'dir. Optional olarak başlamak daha güvenli olabilir. Default davranış kullanılabilir. Consumer migration planı gerekir.

Response Field Silmek

Consumer kaldırılan field'e bağlı olabilir. Compile-time type bozulabilir. UI eksik veri alabilir. Deprecation süreci uygulanmalıdır. Major release ile kaldırılabilir.

Data Type Değiştirmek

String'den integer'a geçiş client parser'ını bozabilir. Generated SDK type değiştirir. Database migration'dan bağımsız değerlendirilmelidir. Yeni field eklemek daha güvenli olabilir. Diff kontrolü zorunludur.

Enum Değerlerini Daraltmak

Mevcut enum değerini kaldırmak breaking değişikliktir. Consumer eski değeri gönderebilir. Validation başarısız olur. Deprecation uygulanmalıdır. Yeni version gerekebilir.

Security Gereksinimini Değiştirmek

Public endpoint'e yeni authentication eklemek consumer'ı kırabilir. Scope daraltmak da etki yaratır. Security değişikliği özel review gerektirir. Migration süresi verilmelidir. Changelog'da açıkça belirtilmelidir.

operationId Değiştirmenin SDK Etkisi

Generator method adını değiştirebilir. Existing SDK consumer compile hatası alabilir. HTTP endpoint aynı olsa da client API değişir. Diff aracı operationId'yi izlemelidir. SDK release major olabilir.

OpenAPI Diff ile Breaking Change Detection

OpenAPI diff yaklaşımı önceki canonical specification ile pull request içindeki yeni specification'ı yapısal olarak karşılaştırır. Böylece yalnız metin satırı değişikliği değil, contract anlamındaki farklar görülebilir. Kırıcı ve geriye uyumlu değişikliklerin ayrılması review kalitesini artırır. Onaysız breaking change merge aşamasında engellenebilir. Gerektiğinde istisna kaydı ve migration planıyla approved breaking change süreci uygulanabilir.

Base Specification

Base spec karşılaştırmanın referansıdır. Genellikle main branch'teki son contract kullanılır. Doğru API sürümü seçilmelidir. Artifact güvenilir kaynaktan alınmalıdır. Cache problemi önlenmelidir.

Pull Request Specification

Yeni spec geliştiricinin önerdiği değişikliği taşır. Generated ise önce build edilmelidir. Validation geçmelidir. Base ile karşılaştırılır. Sonuç pull request'e yorum olarak eklenebilir.

Structural Diff

Structural diff YAML satırlarından fazlasını inceler. Operation ve schema değişikliğini anlar. Ordering farklarını önemsemeyebilir. Breaking semantik çıkarabilir. API review için daha anlamlıdır.

Breaking vs Non-Breaking Change

Yeni optional field çoğu durumda geriye uyumlu olabilir. Required field eklemek kırıcıdır. Endpoint eklemek genellikle uyumludur. Security değişikliği özel değerlendirilmelidir. Kurum sınıflandırmayı belgelemelidir.

Breaking Change Raporu

Rapor değişikliğin yerini göstermelidir. Etkilenen operation belirtilmelidir. Risk seviyesi yazılabilir. Migration ihtiyacı açıklanabilir. Reviewer hızlı karar verebilir.

Merge'i Engellemek

Onaysız breaking change CI tarafından engellenebilir. Developer gerekli migration'ı hazırlar. API owner approval verir. Changelog güncellenir. Sonra kontrollü merge yapılır.

Approved Breaking Change

Bazen kırıcı değişiklik kaçınılmazdır. Major version hazırlanabilir. Consumer'lara süre verilir. Exception kaydı tutulur. Otomasyon approval bilgisini kontrol edebilir.

API Versioning Nasıl Yapılmalı?

API versioning breaking change yönetiminin araçlarından biridir. URI, header, media type veya query parameter üzerinden sürüm seçimi yapılabilir. Public API'lerde görünür ve kolay anlaşılır model çoğu zaman önemlidir. Internal API'lerde de consumer bağımlılığı olduğu için versioning tamamen gereksiz kabul edilmemelidir. Hangi model seçilirse seçilsin kurum genelinde aynı stratejinin uygulanması entegrasyon deneyimini iyileştirir.

URI Versioning

URI versioning sürümü path içinde gösterir. Kullanımı kolaydır. Developer tarafından hemen fark edilir. Routing basittir. Major version için sık kullanılan yaklaşımlardan biridir.

/v1/users

v1 ilk major API contract'ını temsil edebilir. URL açık biçimde sürümü gösterir. Consumer hangi version'ı kullandığını bilir. Patch sürümü URI'ye eklemek gerekli değildir. Lifecycle politikası ayrıca tutulmalıdır.

/v2/users

v2 breaking değişiklik için yeni contract sunabilir. v1 geçiş süresince çalışmaya devam eder. Migration guide yayınlanır. Sunset tarihi duyurulur. Consumer kontrollü şekilde taşınır.

Header Versioning

Version header üzerinden seçilebilir. URL daha temiz kalır. Debug sırasında sürüm görünürlüğü azalabilir. Gateway desteği gerekir. Developer tooling için örnekler verilmelidir.

Media-Type Versioning

Media type içinde version taşınabilir. HTTP content negotiation modeline yakındır. Kullanımı daha ileri seviye olabilir. Client örnekleri şarttır. Kurum ekosistemi bunu rahat desteklemelidir.

Query Parameter Versioning

Query parametreyle version seçmek mümkündür. Kullanımı kolay görünür. Cache ve routing davranışı değerlendirilmelidir. Kurum standardı olmadan eklenmemelidir. Public API ergonomisi test edilmelidir.

Public API'lerde Versioning

Public consumer'lar kontrolünüz dışında release yapar. Breaking değişiklik güçlü lifecycle süreci gerektirir. Deprecation uzun tutulabilir. Migration guide hazırlanmalıdır. Version support politikası açık olmalıdır.

Internal API'lerde Versioning

Internal API consumer'ı da production dependency taşır. Monorepo olmak kırılma riskini ortadan kaldırmaz. Etki analizi yapılmalıdır. Gerektiğinde version kullanılmalıdır. Basit servislerde uyumlu evrim tercih edilebilir.

OpenAPI Version ile API Version Aynı Şey midir?

OpenAPI version ile API product version kesinlikle aynı kavram değildir. openapi alanı belgenin hangi OpenAPI Specification sürümüne göre yazıldığını belirtir. info.version ise sizin API ürününüzün sürümünü ifade eder. Örneğin OpenAPI 3.2.0 kullanan bir API'nin kendi sürümü 2.4.0 olabilir. İki değeri ayrı yönetmek ve ekip dokümanında açık biçimde tanımlamak gerekir.

openapi: 3.2.0

Bu değer specification formatını belirtir. API endpoint version'ı değildir. Parser davranışını etkiler. Tooling uyumluluğu buna göre belirlenir. API release notlarıyla doğrudan eşleşmek zorunda değildir.

info.version: 2.4.0

Bu değer API ürün sürümünü temsil edebilir. Semantic versioning kullanılabilir. Changelog ile ilişkilendirilebilir. Consumer release bilgisi olarak sunulabilir. Specification sürümünden bağımsızdır.

Specification Version

Specification version OpenAPI standardının sürümüdür. Syntax ve schema özelliklerini belirler. Tooling bunu okur. Upgrade teknik uyumluluk gerektirir. Product business version'ı değildir.

Product/API Version

Product version API lifecycle'ını anlatır. Major ve minor release kavramlarını içerebilir. Consumer etkisi taşır. Changelog tarafından takip edilir. URI version ile ilişkisi ayrıca tanımlanabilir.

İkisini Karıştırmamak

İki version'ın karıştırılması hatalı migration kararları doğurur. OpenAPI upgrade API breaking change olmak zorunda değildir. API v2 OpenAPI 3.1 ile yazılabilir. Terminoloji dokümanda açık olmalıdır. CI metadata kontrolleri bunu destekleyebilir.

Semantic Versioning API'lerde Nasıl Kullanılır?

Semantic Versioning API contract değişikliklerini sınıflandırmak için faydalı bir model olabilir. Major kırıcı değişikliği, minor geriye uyumlu yeni yeteneği, patch ise uyumlu düzeltmeyi temsil edecek şekilde uygulanabilir. Ancak runtime davranışın gerçek etkisi her zaman değerlendirilmelidir. Sadece version numarası artırmak migration yönetimi sağlamaz. Changelog, deprecation ve consumer notification süreçleri versioning ile birlikte çalışmalıdır.

Major

Major version breaking change'i temsil edebilir. Consumer migration gerektirir. Yeni URI version açılabilir. Eski version geçici süre korunabilir. Release planı önceden duyurulmalıdır.

Minor

Minor geriye uyumlu özellik ekleyebilir. Yeni optional field buna örnek olabilir. Consumer zorunlu değişiklik yapmamalıdır. Unknown field toleransı önemlidir. Changelog güncellenmelidir.

Patch

Patch uyumlu bug fix için kullanılabilir. Contract değişmeyebilir. Dokümantasyon düzeltmesi yapılabilir. Runtime davranış değişikliği yine değerlendirilmelidir. Güvenlik fix'i ayrıca duyurulabilir.

API Contract ile Semantic Version

Version contract etkisine göre artırılmalıdır. Database değişikliği tek başına API version değiştirmez. Public behavior değişikliği esas alınır. Diff otomasyonu karar destek sağlayabilir. Nihai classification review gerektirebilir.

Breaking Change'de Major Version

Kırıcı değişiklik major increment gerektirebilir. Tüm kurum bunu aynı şekilde yorumlamalıdır. Consumer migration planı hazırlanmalıdır. SDK major release ile eşlenebilir. Eski version kapanışı planlanmalıdır.

Backward-Compatible Değişiklikler

Uyumlu değişiklik mevcut consumer'ı bozmaz. Yeni endpoint eklemek buna örnektir. Optional response field genellikle uyumludur. Enum genişletmenin consumer etkisi ayrıca düşünülmelidir. Contract diff otomatik raporlayabilir.

API Deprecation Standardı

Bir endpoint'i kaldırmadan önce consumer'a geçiş süresi vermek kurumsal API yönetiminin temel parçasıdır. Deprecated işareti tek başına yeterli değildir. Deprecation date, sunset date, migration guide ve changelog birlikte sunulmalıdır. Consumer notification kanalı önceden tanımlanmalıdır. Eski version ancak aktif tüketicilerin durumu görüldükten ve destek politikası karşılandıktan sonra kapatılmalıdır.

deprecated

OpenAPI operation deprecated olarak işaretlenebilir. UI bunu görünür hale getirebilir. Alternatif endpoint description içinde verilebilir. Tek başına migration sağlamaz. Lifecycle metadata ile desteklenmelidir.

Deprecation Date

Deprecation tarihi kullanımın artık önerilmediği zamanı belirtir. Consumer planlama yapar. Catalog içinde saklanabilir. Changelog'a eklenmelidir. Tarih formatı standardize edilmelidir.

Sunset Date

Sunset date hizmetin kapanacağı zamanı gösterir. Yeterli süre önceden duyurulmalıdır. Public API policy minimum süre belirleyebilir. Consumer kullanım metriği izlenmelidir. Gerekirse tarih kontrollü biçimde uzatılabilir.

Migration Guide

Migration guide eski ve yeni davranış farkını açıklar. Kod örneği sunabilir. Field mapping gösterilebilir. Breaking noktalar öne çıkarılır. Consumer'ın tahmin yapması engellenir.

Changelog

Changelog lifecycle değişikliğini kaydeder. Deprecated ve removed bölümleri bulunabilir. Tarih eklenir. Migration link'i verilir. API portalında görünür olmalıdır.

Consumer Notification

Consumer yalnız dokümanı düzenli kontrol etmeyebilir. E-posta veya portal bildirimi gerekebilir. Internal sistemde owner'a otomatik mesaj gönderilebilir. Kritik değişiklikler tekrarlı duyurulabilir. Bildirim kaydı tutulmalıdır.

Eski Version'ı Ne Zaman Kapatmalı?

Sunset policy karşılanmadan kapatılmamalıdır. Aktif trafik ölçülmelidir. Kritik consumer kalıp kalmadığı görülmelidir. Migration desteği tamamlanmalıdır. Son karar API owner tarafından onaylanmalıdır.

API Changelog Nasıl Yazılmalı?

Changelog consumer'ın API'de ne değiştiğini hızlı biçimde görmesini sağlar. Added, Changed, Deprecated, Removed, Fixed ve Security gibi kategoriler anlaşılır bir düzen oluşturur. Breaking change normal değişikliklerin arasında kaybolmamalıdır. Her kırıcı değişiklik migration bağlantısı ve etkilenen version bilgisiyle öne çıkarılmalıdır. Changelog release pipeline tarafından güncellenebilir fakat içerik yine insan tarafından okunabilir olmalıdır.

Added

Yeni geriye uyumlu özellikler burada listelenir. Endpoint eklenebilir. Optional field eklenebilir. Release tarihi bulunmalıdır. Consumer etkisi kısaca açıklanmalıdır.

Changed

Mevcut davranış değişiklikleri burada yazılır. Compatibility etkisi belirtilmelidir. Performance değişikliği de eklenebilir. Contract farkı açık olmalıdır. Belirsiz “iyileştirildi” ifadelerinden kaçınılmalıdır.

Deprecated

Kullanımdan kaldırılması planlanan özellikler listelenir. Alternatif gösterilir. Deprecation tarihi yazılır. Sunset tarihi verilmelidir. Migration guide eklenebilir.

Removed

Kaldırılan özellikler açıkça belirtilir. Hangi version'da kaldırıldığı yazılır. Önceki deprecation kaydına bağlanabilir. Migration yolu gösterilir. Breaking etiketi eklenmelidir.

Fixed

Bug fix'ler burada listelenir. Consumer davranışını etkileyen fix açıklanmalıdır. Contract değişikliği varsa ayrıca gösterilmelidir. Güvenlik düzeltmesi farklı bölümde olabilir. Gereksiz implementasyon ayrıntısı eklenmemelidir.

Security

Security değişiklikleri görünür olmalıdır. Hassas exploit ayrıntısı yayınlanmayabilir. Consumer action gerekiyorsa açıkça belirtilmelidir. Credential rotation bilgisi verilebilir. Release tarihi bulunmalıdır.

Breaking Change'leri Öne Çıkarmak

Kırıcı değişiklik ayrı işaretlenmelidir. Etkilenen endpoint belirtilmelidir. Migration zamanı yazılmalıdır. SDK etkisi açıklanmalıdır. Consumer sürpriz yaşamamalıdır.

Migration Link'i Eklemek

Changelog kısa bilgi verir. Ayrıntı migration guide içinde tutulabilir. Link kalıcı olmalıdır. Versiyon eşleşmesi açık olmalıdır. Kırık link CI ile kontrol edilebilir.

Mock Server Nedir?

Mock server gerçek API implementasyonu tamamlanmadan OpenAPI sözleşmesine göre örnek response döndüren test ortamıdır. Frontend, mobil ve partner ekipleri bu sayede paralel çalışabilir. Mock yalnız hız sağlamaz, aynı zamanda tasarımın tüketici açısından kullanılabilir olup olmadığını da erken gösterir. Example veriler yetersizse mock deneyimi de yetersiz kalır. Bu nedenle request ve response examples contract tasarımının önemli parçası olarak ele alınmalıdır.

OpenAPI'den Mock Response

Mock server spec içindeki schema ve example'ları kullanabilir. Endpoint davranışı simüle edilir. Backend gerekmez. Consumer ilk entegrasyonu deneyebilir. Mock sonucu gerçek contract ile aynı formatta olmalıdır.

Frontend Development

Frontend mock API'ye bağlanabilir. UI state'leri geliştirilebilir. Loading ve error ekranları test edilebilir. Backend bekleme süresi azalır. Integration aşamasında contract değişikliği daha az olur.

Mobile Development

Mobil ekip de mock contract kullanabilir. Model generation yapılabilir. Offline testler hazırlanabilir. Version compatibility erken düşünülebilir. Gerçek API hazır olduğunda geçiş kolaylaşır.

Partner Entegrasyonu

Partner ekip erken sandbox deneyimi elde eder. Credential gereksinimi azaltılabilir. Request formatı test edilir. Feedback tasarım aşamasında alınır. Production onboarding süresi kısalır.

API Implementation Öncesi Test

Contract kullanılabilirliği koddan önce test edilir. Eksik field fark edilir. Yanlış naming ortaya çıkar. Pagination modeli denenir. Değişiklik maliyeti düşükken düzeltme yapılır.

Example'ların Mock Kalitesine Etkisi

Example gerçekçi değilse mock faydası azalır. Null senaryoları gösterilmelidir. Error response örneklenmelidir. PII kullanılmamalıdır. CI schema uyumunu doğrulamalıdır.

Swagger/OpenAPI ile SDK Generation

OpenAPI specification'ı TypeScript, Python, Java, Go ve C# gibi farklı dillerde client SDK üretiminin girdisi olabilir. Burada schema isimleri ve operationId kalitesi doğrudan developer experience üzerinde etkili olur. generated SDK'yı insan eliyle sürekli düzeltmek yerine generator config ve spec iyileştirilmelidir. Her SDK release'i integration testlerinden geçmelidir. API breaking change süreci SDK versioning stratejisiyle birlikte yönetilmelidir.

OpenAPI Generator

OpenAPI Generator çeşitli diller için code generation sağlar. Template seçenekleri bulunur. Config versionlanmalıdır. Generated kod test edilmelidir. Upgrade çıktısı diff ile incelenmelidir.

Swagger Codegen

Swagger Codegen de specification'dan kod üretebilir. Dil desteği geniş olabilir. Proje ihtiyaçlarına göre değerlendirilmelidir. operationId ve schema isimleri sonucu etkiler. Tool version'ı sabitlenmelidir.

TypeScript SDK

TypeScript SDK frontend ekipleri için güçlü type desteği sağlar. Schema type'lara dönüşür. Nullable davranış önemlidir. Runtime error handling ayrıca gerekir. Package registry üzerinden dağıtılabilir.

Python SDK

Python client server API'sini programatik kullanımı kolaylaştırır. Type hint üretilebilir. Authentication helper eklenebilir. Generated model ergonomisi test edilmelidir. Package version API release ile ilişkilendirilebilir.

Java SDK

Java SDK güçlü typed modeller sunabilir. Enum değişiklikleri compile etkisi yaratabilir. Nullable alanlar dikkat gerektirir. HTTP client seçimi config ile yapılabilir. Integration test zorunlu tutulmalıdır.

Go SDK

Go SDK struct modelleri üretebilir. Pointer kullanımı optional alanlarda önemlidir. Error handling Go convention'ına uyarlanmalıdır. Generated API okunabilir olmalıdır. Tool upgrade diff'i incelenmelidir.

C# SDK

C# SDK .NET tüketicileri için generated client sağlayabilir. Nullable reference type davranışı önemlidir. Enum ve date-time mapping test edilmelidir. Authentication handler eklenebilir. Package release otomatikleştirilebilir.

operationId ve Schema İsimlerinin SDK Kalitesine Etkisi

Kötü operationId kötü method adı üretir. Generic schema isimleri okunabilirliği düşürür. Stable naming backward compatibility sağlar. SDK consumer'ı doğrudan etkilenir. Bu yüzden naming yalnız doküman estetiği değildir.

Generated SDK'lar Nasıl Yönetilmeli?

Generated SDK'nın güvenilir olabilmesi için build ve release süreci otomatik olmalıdır. Kod üzerinde manuel değişiklik yapılırsa sonraki generation çalışmasında değişiklikler kaybolabilir. Bu nedenle düzeltme mümkün olduğunca specification, template veya generator configuration üzerinden yapılmalıdır. SDK versioning API lifecycle ile ilişkilendirilmeli ve package registry üzerinden düzenli biçimde yayımlanmalıdır. Integration testler gerçek staging API üzerinde temel operasyonları doğrulamalıdır.

SDK Versioning

SDK kendi semantic version'ına sahip olabilir. API breaking change major release gerektirebilir. Changelog tutulmalıdır. Supported API version açık olmalıdır. Consumer migration bilgisi verilmelidir.

Otomatik Build

SDK build pipeline tarafından üretilmelidir. Aynı config her seferinde kullanılmalıdır. Deterministik output tercih edilmelidir. Test otomatik çalışmalıdır. Artifact güvenilir registry'ye gönderilmelidir.

Package Registry

SDK package registry üzerinden dağıtılabilir. Version immutable olmalıdır. Release notes eklenmelidir. Access policy uygulanabilir. Deprecated package sürümleri işaretlenebilir.

Generated Code'a Manuel Müdahale Etmemek

Manuel patch tekrar generation'da kaybolur. Kaynak sorunu spec veya template'de çözmek daha iyidir. Generated klasör işaretlenebilir. Code review beklentisi buna göre ayarlanır. İstisna varsa belgelenmelidir.

SDK Integration Tests

SDK gerçek API ile test edilmelidir. Authentication doğrulanır. Serialization hataları yakalanır. Error handling kontrol edilir. Release öncesi staging üzerinde çalıştırılabilir.

Breaking API Change ile SDK Release'i Eşlemek

API major değişikliği SDK major release gerektirebilir. Consumer hangi kombinasyonun uyumlu olduğunu bilmelidir. Release matrix tutulabilir. Migration guide ikisini birlikte açıklamalıdır. Automation eşleşmeyi kontrol edebilir.

Contract Testing Nedir?

Contract testing, gerçek API davranışının OpenAPI specification ile uyumlu olup olmadığını otomatik olarak doğrulayan test yaklaşımıdır. Request ve response schema, status code ve header kuralları bu testlerde kontrol edilebilir. Dokümantasyonun güncelliğini korumanın en güvenilir yollarından biridir. Özellikle code-first dışında kalan sistemlerde spec drift'i yakalamak için güçlü koruma sağlar. CI pipeline içinde çalıştığında sözleşme dışı değişiklik production'a ulaşmadan görülebilir.

API Spec ile Gerçek Response'u Karşılaştırmak

Test endpoint'i çağırır. Response schema spec'ten okunur. Gerçek payload validate edilir. Fazladan veya eksik field davranışı kontrol edilir. Drift raporlanır.

Request Validation

Gönderilen request schema'ya göre kontrol edilebilir. Required alanlar doğrulanır. Type hataları bulunur. Header gereksinimleri test edilir. Negative test üretilebilir.

Response Validation

Response body contract ile karşılaştırılır. Required field eksikliği bulunur. Type mismatch yakalanır. Unexpected content type fark edilir. Consumer sürprizleri azalır.

Schema Validation

Schema validation veri yapısını kontrol eder. Enum ve format doğrulanabilir. Nested object incelenir. Null davranışı test edilir. Tooling OpenAPI sürümüyle uyumlu olmalıdır.

Status Code Validation

Beklenen status code specification'da bulunmalıdır. Gerçek API farklı kod döndürürse test başarısız olabilir. Error senaryoları özellikle çalıştırılmalıdır. Sadece happy path yeterli değildir. Kurumsal status policy doğrulanır.

Header Validation

Gerekli response header'ları kontrol edilir. Correlation ID buna örnektir. Content-Type doğrulanır. Rate limit header'ları test edilebilir. Format sözleşmeyle eşleşmelidir.

CI Pipeline'da Contract Test

Contract test deployment öncesi çalıştırılır. Staging API hedeflenebilir. Failure release'i durdurabilir. Rapor artifact olarak saklanır. API quality score'a aktarılabilir.

OpenAPI Example'ları Nasıl Test Edilir?

Example veriler zamanla schema'dan kopabilir. Bu nedenle örneği yalnız dokümantasyon metni olarak değil, test edilebilir veri olarak görmek gerekir. Request example schema ile validate edilmeli, response example da ilgili response modeline uymalıdır. CI içinde bu kontrol çalıştırıldığında stale example problemi erken görülür. Çalışmayan örneklerin yayınlanması geliştirici güvenini hızlı biçimde düşürdüğü için bu kontrol yatırım yapmaya değerdir.

Example ile Schema Uyumu

Example schema kurallarını karşılamalıdır. Required alan bulunmalıdır. Enum değeri geçerli olmalıdır. Format doğru olmalıdır. CI otomatik validation yapabilir.

Request Example

Request example gerçek kullanım senaryosu göstermelidir. Minimum çalışan payload eklenebilir. Opsiyonel alanlı ikinci örnek bulunabilir. Secret kullanılmamalıdır. Server validation ile uyumlu olmalıdır.

Response Example

Response example consumer beklentisini somutlaştırır. Schema ile birebir uyumlu olmalıdır. Null alan davranışı gösterilebilir. Error example eklenmelidir. Gerçek müşteri verisi kullanılmamalıdır.

CI'da Example Validation

Pipeline spec'i parse eder. Examples schema ile karşılaştırılır. Hata build'i durdurabilir. Böylece eski örnek yayınlanmaz. Coverage metriği ayrıca tutulabilir.

Çalışmayan Kod Örneklerini Tespit Etmek

cURL veya SDK snippet'leri de test edilebilir. Staging üzerinde smoke test çalıştırılabilir. Expired endpoint fark edilir. Authentication değişikliği yakalanır. Doküman gerçek sistemle senkron kalır.

Stale Example Problemi

Schema değişir fakat example güncellenmezse stale hale gelir. Consumer yanlış payload kopyalar. Support talepleri artar. CI validation sorunu erken bulur. Docs review de yardımcı olur.

API Dokümantasyonunda Kod Örnekleri

Kod örnekleri geliştiricinin reference bilgisini çalışan entegrasyona dönüştürmesini kolaylaştırır. cURL her dil için ortak başlangıç sağlar. JavaScript, Python, Java, C# ve Go gibi sık kullanılan diller için örnekler eklemek farklı consumer ekiplerini destekler. İyi örnek authentication ve error handling davranışını da gösterir. Mümkünse snippet'ler CI üzerinde gerçek veya kontrollü staging ortamında test edilmelidir.

cURL

cURL en taşınabilir request örneklerinden biridir. Header'lar açıkça görünür. Authentication gösterilebilir. Debug için kolaydır. Gerçek secret kullanılmamalıdır.

JavaScript

JavaScript örneği web geliştiricilerine yardımcı olur. fetch kullanılabilir. Error status kontrol edilmelidir. Token placeholder kullanılmalıdır. Async davranış doğru gösterilmelidir.

Python

Python örneği kısa ve okunabilir olabilir. HTTP client kullanımı gösterilir. Timeout eklenmelidir. Error response kontrol edilir. Secret environment variable üzerinden alınabilir.

Java

Java örneği typed SDK veya HTTP client kullanabilir. Exception handling gösterilmelidir. Timeout ayarı bulunmalıdır. Authentication header eklenebilir. Kod mümkün olduğunca çalıştırılabilir olmalıdır.

C#

C# örneği HttpClient veya generated SDK kullanabilir. Async method tercih edilebilir. Status code kontrol edilir. Cancellation token eklenebilir. Credential kod içine gömülmemelidir.

Go

Go örneği context ve timeout kullanmalıdır. Error kontrolü açık yapılır. Response body güvenli biçimde kapatılır. Authentication header eklenebilir. JSON decode hatası işlenmelidir.

Complete Runnable Example

Örnek yalnız birkaç satır pseudo code olmamalıdır. Import bilgileri bulunabilir. Gerekli environment variable açıklanır. Başarılı çıktı gösterilebilir. Repository içinde test edilebilir örnek sağlanabilir.

Authentication Dahil Örnek

Gerçek entegrasyon çoğu zaman authentication gerektirir. Placeholder token gösterilmelidir. Credential alma rehberine bağlantı verilebilir. Secret hardcode edilmemelidir. Refresh davranışı gerektiğinde açıklanmalıdır.

Error Handling Örneği

Sadece happy path göstermek eksiktir. 400 ve 401 davranışı ele alınmalıdır. Error body parse edilmelidir. Retry yalnız uygun durumda yapılmalıdır. Correlation ID loglanabilir.

Getting Started Bölümü Nasıl Tasarlanmalı?

Getting Started bölümünün temel hedefi geliştiriciyi mümkün olduğunca hızlı ilk başarılı request'e ulaştırmaktır. Credential alma, authentication, base URL ve ilk çağrı tek bir akış halinde sunulmalıdır. İlk response gösterilmeli ve hata durumunda nereye bakılacağı açıklanmalıdır. On yılı aşan projelerde gördüğüm en iyi onboarding ölçüsü, geliştiricinin doküman açıldıktan sonraki 5 ile 10 dakika içinde çalışan çağrı yapabilmesidir. Bu süre uzuyorsa dokümantasyon veya credential provisioning süreci yeniden incelenmelidir.

API Credential Alma

Credential provisioning adımları açık olmalıdır. Hangi portalın kullanılacağı belirtilmelidir. Test credential ile production ayrılmalıdır. Approval süresi varsa yazılmalıdır. Secret güvenli biçimde saklanmalıdır.

Authentication

İlk request için gereken auth yöntemi gösterilmelidir. Header formatı örneklenmelidir. Scope gereksinimi açıklanmalıdır. Gerçek token kullanılmamalıdır. Sık auth hataları ayrıca yazılabilir.

Base URL

Staging base URL açıkça gösterilmelidir. Production adresi ayrıca belirtilir. Region farkı varsa açıklanır. HTTPS kullanılmalıdır. Eski hostlar dokümandan kaldırılmalıdır.

İlk Request

İlk request mümkün olduğunca basit olmalıdır. Read-only endpoint tercih edilebilir. cURL örneği verilebilir. Authentication dahil edilmelidir. Gereksiz parametrelerden kaçınılmalıdır.

İlk Response

Başarılı response örneklenmelidir. Önemli alanlar kısa açıklanır. Status code belirtilir. Correlation ID gösterilebilir. Consumer doğru sonucu hemen anlayabilmelidir.

Hata Durumunda Ne Yapmalı?

En yaygın 401 ve 403 sorunları açıklanmalıdır. Base URL kontrolü önerilebilir. Error code kataloğuna yönlendirme yapılabilir. Support kanalı verilmelidir. Correlation ID paylaşılması istenebilir.

5–10 Dakikada İlk Başarılı Çağrı

Bu hedef onboarding kalitesini ölçer. Credential süresi ayrıca hesaplanabilir. Dokümantasyon adımları gereksiz uzamamalıdır. Kullanıcı testleri yapılabilir. Sonuç API scorecard'a eklenebilir.

API Reference ile Tutorial Arasındaki Fark

API Reference belirli bir endpoint'in teknik sözleşmesini verir, tutorial ise geliştiriciyi gerçek bir hedefe adım adım ulaştırır. Concept içeriği sistemin nasıl düşündüğünü açıklar. How-To Guide belirli bir işi nasıl yapacağını gösterir. Quickstart ilk başarılı çağrıya odaklanır. Her şeyi Swagger UI description alanlarına sıkıştırmak yerine içerik tiplerini doğru yerlere ayırmak daha okunabilir bir developer portal oluşturur.

Reference

Reference kesin teknik bilgi sunar. Parameter ve schema burada bulunur. Hızlı lookup için uygundur. Baştan sona okunmak zorunda değildir. OpenAPI'den üretilebilir.

Concept

Concept temel fikirleri açıklar. Authentication modeli buna örnektir. Endpoint detayından daha geniştir. Sistem davranışını anlamayı sağlar. Developer portal içinde ayrı bölüm olabilir.

How-To Guide

How-To belirli bir görevi çözer. Örneğin webhook doğrulaması anlatılabilir. Adımlar pratiktir. Gereksiz teori içermez. İlgili reference linkleri eklenir.

Tutorial

Tutorial öğrenme yolculuğu sunar. Baştan sona takip edilir. Çalışan örnek üretir. Kavramları sırayla tanıtır. Yeni geliştiriciler için değerlidir.

Quickstart

Quickstart hızlı ilk sonuç sağlar. Minimum adım içerir. Credential ve ilk request gösterilir. Ayrıntılar sonraki rehberlere bırakılır. Onboarding için güçlü giriş noktasıdır.

Her Şeyi Swagger UI İçine Yazmaya Çalışmamak

Swagger UI reference konusunda güçlüdür. Uzun tutorial için ideal yer olmayabilir. Business workflow ayrı guide gerektirir. Migration içeriği portalda tutulabilir. Kullanıcı doğru bilgi türünü doğru yerde bulmalıdır.

Developer Portal Nasıl Yapılandırılmalı?

Developer portal API tüketicisinin yalnız endpoint listesini değil, tüm entegrasyon yaşam döngüsünü bulduğu merkez olmalıdır. Getting Started, Authentication, Guides ve API Reference temel bölümlerdir. SDK, webhook, changelog, status ve support içerikleri operasyonel deneyimi tamamlar. Reference OpenAPI'den otomatik üretilebilir, diğer rehberler docs-as-code yaklaşımıyla yönetilebilir. Portal araması ve navigasyonu büyük API ekosistemlerinde özellikle önemlidir.

Getting Started

Başlangıç yolu görünür olmalıdır. İlk request hedeflenir. Gereksiz seçim azaltılır. Sandbox bilgisi eklenir. Sonraki rehberlere yönlendirme yapılır.

Authentication

Auth modelleri merkezi açıklanmalıdır. Credential alma süreci bulunur. Scope detayları yazılır. Refresh davranışı gösterilir. Güvenlik önerileri eklenir.

Guides

Guide'lar gerçek iş akışlarını anlatır. Pagination kullanımı gösterilebilir. Webhook doğrulaması açıklanabilir. Error recovery işlenebilir. Reference linkleri eklenmelidir.

API Reference

Reference canonical spec'ten üretilmelidir. Search özelliği bulunmalıdır. Tag yapısı anlaşılır olmalıdır. Version seçimi görünür tutulmalıdır. Manual kopya yapılmamalıdır.

SDKs

Desteklenen SDK'lar listelenmelidir. Package version gösterilebilir. Installation komutu bulunmalıdır. Changelog linklenebilir. Source repository bilgisi verilebilir.

Webhooks

Webhook event katalogu bulunmalıdır. Payload schema gösterilir. Signature verification açıklanır. Retry policy yazılır. Test yöntemi sunulur.

Changelog

API değişiklikleri burada görülebilmelidir. Breaking değişiklik öne çıkarılmalıdır. Deprecation tarihi bulunur. Migration linki eklenir. RSS veya bildirim desteği düşünülebilir.

Status

Service status entegrasyon sorunlarını ayırmaya yardımcı olur. Incident bilgisi gösterilebilir. Historical uptime sunulabilir. API consumer debugging süresi azalır. Internal sistemlerde de faydalıdır.

Support

Support yolu açık olmalıdır. API owner bilgisi bulunabilir. Ticket kanalına yönlendirme yapılabilir. Correlation ID paylaşma adımı açıklanabilir. Yanıt beklentisi belirtilmelidir.

Swagger UI Tek Başına API Dokümantasyonu İçin Yeterli mi?

Swagger UI endpoint reference için çok güçlüdür fakat tek başına eksiksiz developer documentation sağlamaz. API'nin iş akışını, onboarding sürecini ve migration stratejisini OpenAPI operation description içine sıkıştırmak okunabilirliği düşürür. Authentication rehberi, tutorial ve business workflow anlatımları ayrı içerikler gerektirir. Swagger UI canonical contract'ın görsel katmanı olarak kullanılmalıdır. Developer portal ise kavramsal ve öğretici içeriği bunun çevresinde birleştirmelidir.

Endpoint Reference İçin Güçlü Yanları

Endpoint listesi otomatik oluşur. Parameters görünür. Schema modelleri açılabilir. Try It Out kullanılabilir. Spec değişince reference güncellenebilir.

Kavramsal İçerik Eksikliği

Concept açıklaması uzun form içerik gerektirebilir. Swagger UI buna sınırlı alan sunar. Architecture anlatımı ayrı guide olabilir. Domain terimleri sözlükte tutulabilir. Portal yapısı daha uygundur.

Business Workflow Açıklamaları

Birden fazla endpoint sırası business workflow oluşturabilir. Reference her operation'ı ayrı gösterir. Akış diyagramı gerekebilir. Tutorial kullanılmalıdır. Error recovery ayrıca anlatılmalıdır.

Tutorial Gereksinimi

Yeni kullanıcı adım adım rehbere ihtiyaç duyar. İlk credential alınır. Request gönderilir. Sonraki işlem yapılır. Reference bu öğrenme sırasını tek başına sağlamaz.

Migration Guide

Version geçişi karşılaştırmalı açıklama gerektirir. Eski ve yeni field eşleştirilir. Kod örneği sunulur. Deadline belirtilir. Ayrı guide daha okunabilir olur.

Authentication Guide

Auth yalnız securitySchemes tanımı değildir. Credential provisioning açıklanmalıdır. Token lifecycle anlatılmalıdır. Scope seçimi gösterilmelidir. Troubleshooting içeriği eklenmelidir.

Swagger UI + Developer Portal Yaklaşımı

İki araç birbirini tamamlar. Swagger UI reference sağlar. Portal guide ve tutorial sunar. Tek canonical spec kullanılır. Kullanıcı ihtiyacına göre doğru içeriğe ulaşır.

Webhook'lar OpenAPI ile Nasıl Dokümante Edilir?

Webhook dokümantasyonu tüketicinin bu kez request gönderen değil, request alan taraf olduğunu hesaba katmalıdır. Event name ve payload schema açıkça belirtilmelidir. Signature verification, retry policy ve delivery attempt davranışı güvenilir entegrasyon için kritiktir. Idempotency consumer'ın aynı event'i birden fazla kez güvenli biçimde işlemesine yardımcı olur. Test webhook aracı onboarding deneyimini önemli ölçüde iyileştirebilir.

Webhook Kavramı

Webhook event oluştuğunda consumer endpoint'ine request gönderir. Polling ihtiyacını azaltır. Consumer public endpoint sağlar. Güvenlik doğrulaması gerekir. Delivery garantisi açıkça belirtilmelidir.

Event Name

Event name sabit convention izlemelidir. order.created gibi yapı kullanılabilir. İsim değişikliği breaking olabilir. Event kataloğu tutulmalıdır. Deprecated event planı olmalıdır.

Payload

Payload schema OpenAPI içinde tanımlanabilir. Event metadata eklenebilir. Resource snapshot bulunabilir. Version bilgisi düşünülebilir. PII gereksiz yere taşınmamalıdır.

Signature Verification

Consumer gelen isteğin gerçekten sağlayıcıdan geldiğini doğrulamalıdır. Signature header kullanılabilir. Verification algoritması rehberde açıklanmalıdır. Secret rotation desteklenmelidir. Replay attack önlemleri düşünülmelidir.

Retry Policy

Webhook teslimatı başarısız olabilir. Retry sayısı belirtilmelidir. Backoff stratejisi açıklanmalıdır. Hangi status code'un retry tetiklediği yazılmalıdır. Consumer duplicate event'e hazırlıklı olmalıdır.

Delivery Attempts

Her attempt loglanabilir. Consumer dashboard'da görebilir. Son response code gösterilebilir. Manual retry özelliği sunulabilir. Retention süresi belirtilmelidir.

Idempotency

Aynı event birden fazla kez gelebilir. Event ID kullanılmalıdır. Consumer işlenmiş ID'yi saklayabilir. Duplicate davranışı açık olmalıdır. Exactly-once varsayımı yapılmamalıdır.

Test Webhook

Test event onboarding'i kolaylaştırır. Kullanıcı endpoint'ini doğrular. Signature davranışını deneyebilir. Farklı event türleri seçilebilir. Production verisi kullanılmamalıdır.

OpenAPI ve AsyncAPI Arasındaki Fark

OpenAPI ağırlıklı olarak HTTP request ve response API'lerini tanımlamak için kullanılır. Event-driven sistemlerde ise mesaj kanalları ve asenkron iletişim için farklı ihtiyaçlar ortaya çıkar. AsyncAPI bu tür kullanım senaryolarını modellemeye odaklanır. Kafka, message queue veya belirli WebSocket senaryolarında event contract'ı ayrı biçimde ele alınabilir. Bir kurum aynı platformda OpenAPI ve AsyncAPI kullanarak synchronous ve asynchronous sözleşmeleri birlikte yönetebilir.

HTTP Request/Response API

OpenAPI bu model için güçlüdür. Client request gönderir. Server response döndürür. Paths ve operations kullanılır. REST API'lerde yaygın biçimde uygulanır.

Event-Driven API

Event-driven model producer ve consumer ilişkisine dayanır. Mesaj zamanlaması farklıdır. Delivery semantics önemlidir. Channel ve message schema öne çıkar. AsyncAPI bu alan için uygundur.

Kafka

Kafka topic tabanlı event iletişiminde kullanılır. Message schema önemlidir. Consumer group davranışı vardır. OpenAPI bu modeli doğal biçimde tanımlamaz. Event specification yaklaşımı tercih edilmelidir.

WebSocket

WebSocket çift yönlü sürekli bağlantı sağlar. Basit request response modelinden farklıdır. Message contract ayrıca tanımlanmalıdır. Protokol davranışı açık olmalıdır. Uygun specification seçilmelidir.

Message Queue

Queue tabanlı sistem asenkron işleme sağlar. Ack ve retry davranışı önemlidir. Message payload schema gerekir. Dead-letter politikası olabilir. Event dokümantasyonu bu davranışları kapsamalıdır.

AsyncAPI Ne Zaman Kullanılmalı?

Mesaj ve channel odaklı contract gerektiğinde değerlendirilebilir. Event producer consumer ilişkisi varsa uygundur. Kafka gibi sistemlerde faydalıdır. HTTP API için OpenAPI kullanılmaya devam edebilir. Araç seçimi protokole göre yapılmalıdır.

OpenAPI ve AsyncAPI'yi Birlikte Kullanmak

Bir mikroservis hem REST hem event sunabilir. REST sözleşmesi OpenAPI olabilir. Event sözleşmesi AsyncAPI olabilir. Ownership bilgisi ortak catalog'da tutulabilir. Governance kuralları iki format için ayrı uygulanabilir.

Mikroservislerde API Dokümantasyon Standardizasyonu

Mikroservis mimarisinde her servis kendi API sözleşmesine sahip olabilir fakat bu sözleşmeler ortak tasarım dilinden kopmamalıdır. Merkezi API Style Guide naming, error model ve security gibi yatay konuları belirler. Shared components gerçekten ortak modeller için kullanılabilir. API catalog servislerin owner, lifecycle ve dependency bilgisini tek yerde toplar. CI governance ise her repository'nin aynı temel kalite kapılarından geçmesini sağlar.

Her Mikroservisin Kendi OpenAPI Dosyası

Servis kendi contract'ını versionlayabilir. Ownership nettir. Deployment bağımsızdır. Spec repository ile birlikte tutulabilir. Catalog merkezi discovery sağlar.

Ortak API Style Guide

Style guide tüm servislerin ortak dilidir. URI ve error standardı sağlar. Authentication convention belirler. Versioning politikası ekler. Ruleset ile otomatik uygulanabilir.

Shared Components

Gerçekten ortak schema merkezi tutulabilir. Error buna örnektir. Her domain modeli paylaşılmamalıdır. Coupling riski düşünülmelidir. Component library versionlanmalıdır.

Merkezi API Catalog

Catalog tüm servisleri listeler. Owner bilgisini gösterir. Spec bağlantısı sunar. Lifecycle state bulunur. Consumer dependency keşfi kolaylaşır.

API Ownership

Her servis sahibi belli olmalıdır. Takım adı tutulur. Support kanalı bulunur. On-call bilgisi eklenebilir. Organizasyon değişikliği catalog'a yansıtılır.

CI Governance

Her repository aynı temel checks'i çalıştırır. Lint uygulanır. Breaking diff kontrol edilir. Contract tests çalışır. Merge politikası merkezi standardı korur.

Versioning

Servisler ortak versioning yaklaşımını izlemelidir. Public ve internal farkı tanımlanabilir. Major değişiklik kontrollü yapılır. Consumer dependency dikkate alınır. Changelog tutulur.

Dependency Mapping

Hangi servis hangi API'yi kullanıyor bilinmelidir. Breaking impact analizi kolaylaşır. Catalog bu ilişkiyi tutabilir. Runtime telemetry destek olabilir. Migration hedefleri doğru ekiplere gönderilir.

API Catalog Nedir?

API Catalog kurum içindeki API envanterini tek noktada görünür hale getirir. Yalnız API adını listelemek yeterli değildir. Owner, lifecycle state, repository, specification, production endpoint ve documentation bağlantıları katalog kaydının parçası olmalıdır. Consumer listesi breaking change impact analizi için özellikle değerlidir. Catalog otomatik güncellendiğinde organizasyon büyüdükçe kaybolan sahiplik bilgisinin önüne geçilebilir.

Kurumdaki API Envanteri

Envanter hangi API'lerin var olduğunu gösterir. Duplicate servisler fark edilir. Discovery kolaylaşır. Shadow API riski azalır. Catalog düzenli güncellenmelidir.

API Owner

Owner sorumlu takımı gösterir. Support soruları doğru yere gider. Breaking change approval sahibi bellidir. On-call bilgisi ilişkilendirilebilir. Sahipsiz API riskli kabul edilmelidir.

Lifecycle State

Lifecycle state API'nin durumunu gösterir. Experimental veya production olabilir. Deprecated state bulunabilir. Consumer risk değerlendirmesi yapar. State geçişleri kurallı olmalıdır.

Repository

Repository contract ve implementation kaynağına yönlendirir. Developer hızlı erişir. Ownership doğrulanabilir. CI metadata okunabilir. Link güncelliği kontrol edilmelidir.

Specification

Catalog canonical OpenAPI spec bağlantısını tutabilir. Version bilgisi gösterilebilir. Validation sonucu eklenebilir. Last updated zamanı bulunabilir. Yanlış kopyaya yönlendirme yapılmamalıdır.

Production Endpoint

Production endpoint discovery için faydalıdır. Public ve internal ayrımı korunmalıdır. Region bilgisi olabilir. Security gereksinimi gösterilebilir. Hassas internal hostname yetkisiz kullanıcıya sunulmamalıdır.

Documentation

Developer portal bağlantısı bulunmalıdır. Getting Started erişilebilir olmalıdır. Reference version ile eşleşmelidir. Changelog linki eklenebilir. Kırık link kontrolü yapılmalıdır.

Consumer Listesi

Consumer listesi impact analysis sağlar. Hangi ekip hangi version'ı kullanıyor görülebilir. Deprecation bildirimi hedeflenir. Migration takibi yapılır. Telemetry ile otomatik güncellenebilir.

OpenAPI Extension (x-) Alanları

OpenAPI extension alanları kuruma özel metadata eklemeye izin verir. x-owner, x-team veya x-lifecycle gibi alanlar governance ve catalog otomasyonunda kullanılabilir. Bu alanlar standardın ana parçası olmadığı için farklı tooling tarafından her zaman anlaşılmayabilir. Extension tasarımı basit tutulmalı ve schema'sı kurum içinde belgelenmelidir. Taşınabilirlik gereksinimi olan bilgiler mümkün olduğunda standart OpenAPI alanlarında tutulmalıdır.

x-owner

x-owner API sahibini gösterebilir. Takım identifier kullanılabilir. Catalog bunu okuyabilir. Linter zorunlu kılabilir. Değer kurum diziniyle doğrulanabilir.

x-team

x-team sorumlu takımı belirtebilir. x-owner ile aynı şeyi tekrar etmemelidir. Anlamı açık tanımlanmalıdır. Tooling buna göre kullanılabilir. Naming convention korunmalıdır.

x-internal

x-internal public olmayan operation'ı işaretlemek için kullanılabilir. Build pipeline filtreleme yapabilir. Tek başına güvenlik sağlamaz. Authorization yine uygulanmalıdır. Public spec generation dikkatle test edilmelidir.

x-lifecycle

x-lifecycle API durumunu taşıyabilir. experimental veya deprecated gibi değerler olabilir. Catalog bu alanı okuyabilir. Enum seti merkezi tanımlanmalıdır. State değişikliği review gerektirebilir.

x-service-name

x-service-name deployment servis adını gösterebilir. Catalog mapping kolaylaşır. Internal naming sızıntısı değerlendirilmelidir. Public spec'te gerekli olmayabilir. Format kurum standardını izlemelidir.

x-codeSamples

x-codeSamples bazı documentation tooling'lerinde kod örneği taşımak için kullanılabilir. Portable olmadığı unutulmamalıdır. Snippet'ler test edilmelidir. Secret içermemelidir. Ana guide içeriğinin tek kopyası olarak kullanılmamalıdır.

Kuruma Özel Metadata

Extension governance için faydalı olabilir. Cost center veya domain bilgisi eklenebilir. Her bilgi için yeni alan açılmamalıdır. Şema ve anlam belgelenmelidir. Automation kullanım amacı olmalıdır.

Extensions'ın Portable Olmadığını Bilmek

x- alanları implementation-specific olabilir. Başka tooling bunları yok sayabilir. Migration sırasında bilgi kaybı yaşanabilir. Kritik contract davranışı extension'a bağlanmamalıdır. Standart alan öncelikli olmalıdır.

API Ownership Nasıl Standardize Edilir?

API sahipliği teknik ve operasyonel sorumluluğu görünür hale getirir. Her API için takım adı, support kanalı, repository ve gerekiyorsa on-call bilgisi bulunmalıdır. Bireysel çalışan adı yerine ekip bazlı sahiplik daha dayanıklıdır. Organizasyon değişikliklerinde catalog metadata'sı otomatik güncellenmelidir. Sahibi bulunamayan API'ler governance açısından ayrı risk kategorisinde değerlendirilmelidir.

Her API'nin Bir Sahibi Olmalı

Sahipsiz API değişiklikte karar veremez. Incident çözümü yavaşlar. Deprecation yapılamaz. Security sorumluluğu belirsizleşir. Catalog owner alanını zorunlu tutmalıdır.

Takım Adı

Takım adı bireysel kişiden daha kalıcıdır. Organizasyon identifier kullanılabilir. x-owner içinde tutulabilir. Catalog ile eşlenebilir. Yeniden yapılanma sonrası güncellenmelidir.

Support Kanalı

Consumer soru sormak için kanal bulabilmelidir. Grup e-posta veya destek sistemi kullanılabilir. Response beklentisi yazılabilir. Link güncel tutulmalıdır. Kişisel hesaplara bağımlılık azaltılmalıdır.

Repository

Repository teknik kaynağı gösterir. Spec burada bulunabilir. Issue takibi yapılabilir. Ownership dosyalarıyla ilişkilendirilebilir. Catalog otomatik discovery yapabilir.

On-Call

Kritik API'lerde on-call bilgisi gerekebilir. Incident routing hızlanır. Public dokümana doğrudan yazılmayabilir. Internal catalog için uygundur. Güncelliği otomatik sistemden alınmalıdır.

Ownership Değişikliğinin Catalog'a Yansıması

Takım değişikliği metadata'yı da güncellemelidir. Manuel işlem unutulabilir. Source of truth organizasyon dizini olabilir. CI senkronizasyon yapabilir. Eski support kanalına yönlendirme kalmamalıdır.

API Governance Nedir?

API governance kurum genelindeki API kalitesini belirli guardrail'lerle koruma yaklaşımıdır. Amaç her tasarım kararını merkezi bir kurulda haftalarca bekletmek değildir. Developer autonomy ile kurumsal standardı birlikte koruyan self-service model daha ölçeklenebilir olur. Policy as code sayesinde ölçülebilen kurallar IDE ve CI içinde otomatik çalışabilir. İnsan review ise gerçekten mimari bağlam gerektiren kararlar için kullanılmalıdır.

Governance'ın Amacı

Amaç tutarlı ve güvenli API üretmektir. Consumer deneyimi korunur. Breaking change kontrol edilir. Ownership görünür olur. Gereksiz bürokrasi hedef değildir.

Merkezi Onay Kurulu mu Otomatik Guardrail mi?

Her değişikliği kuruldan geçirmek ölçeklenmeyebilir. Otomatik guardrail hızlı feedback verir. Kritik istisnalar insan review alır. Risk bazlı yaklaşım kullanılabilir. Bekleme süresi azaltılır.

Developer Autonomy

Geliştirici açık kurallarla bağımsız ilerleyebilmelidir. Tooling anında geri bildirim verir. Standart önceden bilinir. Exception süreci şeffaftır. Governance sürpriz kapı olmamalıdır.

Kurumsal Standart

Standart ortak minimum kaliteyi tanımlar. Error formatı buna örnektir. Security requirement bulunur. Versioning politikası vardır. Tüm servisler aynı temel dili kullanır.

Self-Service

Self-service platform hazır template sunabilir. Starter OpenAPI bulunabilir. Ruleset otomatik gelir. CI pipeline hazır olur. Ekip merkezi yardım beklemeden başlayabilir.

Policy as Code

Policy as code yazılı kuralı otomasyona dönüştürür. Ruleset repository'de versionlanır. Pull request ile değişir. Test edilir. Aynı sonuç her ekipte uygulanır.

API Governance'ı Darboğaza Dönüştürmemek

Çok fazla manuel approval teslimatı yavaşlatır. Otomasyon yaygın kuralları çözmelidir. Riskli değişiklikler insan review almalıdır. Metrics bekleme süresini göstermelidir. Süreç düzenli iyileştirilmelidir.

API Governance Pipeline'ı

İyi bir governance pipeline geliştiricinin OpenAPI değişikliğinden documentation deployment'a kadar olan sürecini otomatik hale getirir. Syntax validation ve Spectral lint ilk kalite kapılarıdır. Security rules, breaking change detection ve contract testleri daha derin kontroller sağlar. Review ve merge sonrasında Swagger UI, SDK ve API catalog aynı contract üzerinden güncellenebilir. Böylece governance ayrı bir bürokratik süreç değil, normal geliştirme pipeline'ının doğal parçası olur.

Developer OpenAPI Dosyasını Değiştirir

Değişiklik branch üzerinde yapılır. IDE lint anında feedback verir. Example güncellenir. Changelog gerektiğinde değiştirilir. Pull request hazırlanır.

Syntax Validation

İlk olarak belge parse edilir. Geçersiz YAML bulunur. OpenAPI yapısı doğrulanır. Hızlı çalışmalıdır. Başarısızsa sonraki adımlar çalışmayabilir.

Spectral Lint

Kurum ruleset'i uygulanır. Naming kontrol edilir. Owner doğrulanır. Error schema aranır. Kritik ihlal build'i durdurur.

Security Rules

Security scheme kontrol edilir. Internal host sızıntısı aranabilir. HTTP server engellenebilir. Secret scanning ayrıca yapılır. Riskli değişiklik security review'a yönlendirilebilir.

Breaking Change Detection

Base ve yeni spec karşılaştırılır. Required field değişimi bulunur. Endpoint kaldırma raporlanır. SDK etkisi değerlendirilir. Onaysız kırıcı fark merge edilmez.

Contract Tests

Staging API contract ile doğrulanır. Response schema test edilir. Header kontrol edilir. Error scenario çalıştırılır. Drift varsa pipeline durur.

Review

İnsan reviewer bağlama odaklanır. Resource design incelenir. Consumer etkisi düşünülür. Security kararı değerlendirilir. Otomasyonun çözemediği konular ele alınır.

Merge

Tüm kalite kapıları geçince merge yapılır. Canonical spec güncellenir. Version history tutulur. Release pipeline tetiklenebilir. Approval kaydı korunur.

Documentation Deployment

Swagger UI yeni spec'i yayınlar. Developer portal reference güncellenir. Cache temizlenir. Version etiketi görünür olur. Broken link kontrolü çalışabilir.

SDK Generation

Spec değişikliği SDK build tetikleyebilir. Generator config kullanılır. Testler çalışır. Uyumlu version hesaplanır. Package registry'ye yayınlanır.

API Catalog Update

Catalog metadata spec'ten okunabilir. Version güncellenir. Owner bilgisi senkron olur. Lifecycle değişikliği yansır. Consumer discovery her zaman güncel kalır.

API Scorecard Nasıl Oluşturulur?

API Scorecard subjektif “doküman iyi görünüyor” değerlendirmesini ölçülebilir kriterlere dönüştürür. Documentation coverage, description ve example oranları temel metrikler olabilir. Error response, security definition ve style guide compliance daha teknik kaliteyi gösterir. Breaking change ve contract test sonuçları yaşam döngüsü disiplinini ölçer. Owner bilgisinin bulunması da kurumsal ölçekte önemli bir kalite göstergesidir.

Documentation Coverage

Kaç operation'ın dokümante olduğu ölçülür. Eksik endpoint görünür olur. Hedef yüzde yüz olabilir. Generated spec avantaj sağlar. Coverage tek başına kaliteyi garanti etmez.

Description Coverage

Summary ve description varlığı ölçülebilir. Empty placeholder kabul edilmemelidir. Kritik operation'lar ayrıca incelenebilir. Trend takip edilir. Ekibin iyileşmesi görünür olur.

Example Coverage

Request ve response example oranı hesaplanabilir. Error example ayrıca ölçülebilir. Schema validation çalıştırılır. Eksik alanlar dashboard'da görünür. Developer experience iyileşir.

Error Response Coverage

Operation'ların hata cevapları kontrol edilir. Sadece 200 dokümante eden endpoint bulunur. Standard error schema kullanımı ölçülür. 401 ve 500 coverage görülebilir. Quality gate yapılabilir.

Security Definition

Protected operation security requirement taşımalıdır. Missing scheme risk oluşturur. Public operation açıkça işaretlenmelidir. Scorecard oran gösterebilir. Security ekibi raporu izleyebilir.

Style Guide Compliance

Spectral sonuçları score'a dönüştürülebilir. Error sayısı ölçülür. Warning trendi takip edilir. Takımlar karşılaştırılabilir. Ceza yerine iyileştirme aracı olarak kullanılmalıdır.

Breaking-Change Compliance

Onaysız breaking change sayısı izlenebilir. Pipeline bypass tespit edilir. Migration kaydı kontrol edilir. Approval oranı görülebilir. Contract disiplini ölçülür.

Contract Test Coverage

Kaç operation runtime test ediliyor ölçülür. Error path coverage eklenebilir. Critical API'ler için yüksek hedef konabilir. Failure trendi takip edilir. Drift riski görünür olur.

Owner Tanımlı mı?

Owner varlığı kolay ölçülebilir. Sahipsiz API hemen bulunur. Support kanalının geçerliliği de kontrol edilebilir. Catalog completeness artar. Operasyonel risk azalır.

API Dokümantasyonu Kalitesi Nasıl Ölçülür?

Dokümantasyon kalitesi yalnız sayfa sayısıyla ölçülmemelidir. Time to First Successful Call, integration completion time ve support ticket sayısı daha anlamlı sonuçlar sunar. Search success ve failed Try-It requests kullanıcıların nerede zorlandığını gösterebilir. Stale documentation rate doğrudan spec drift problemini görünür hale getirir. API adoption ile birlikte değerlendirildiğinde dokümantasyon yatırımının gerçek etkisi anlaşılabilir.

Time to First Successful Call

Kullanıcının ilk çalışan request'e ulaşma süresidir. Quickstart kalitesini ölçer. Credential süreci etkiler. Kullanıcı testleriyle bulunabilir. Süreyi azaltmak güçlü DX hedefidir.

Documentation Search Success

Kullanıcı aradığı bilgiyi bulabiliyor mu ölçülür. Search query analizi yapılabilir. Sıfır sonuçlar incelenir. İçerik isimleri iyileştirilir. Portal bilgi mimarisi gelişir.

Integration Completion Time

Gerçek entegrasyonun tamamlanma süresidir. Dokümantasyon etkisini gösterir. Support bekleme süresi dahil edilebilir. Partner bazında ölçülebilir. İyileştirme sonrası trend takip edilir.

Support Ticket Sayısı

Sık ticket doküman boşluğuna işaret edebilir. Kategori analizi yapılmalıdır. Tekrarlanan auth soruları rehberi iyileştirir. Ticket azalması başarı sinyali olabilir. Yine de düşük ticket tek başına yeterli metrik değildir.

Failed Try-It Requests

Try It Out hata oranı problem gösterebilir. CORS sık sebep olabilir. Expired token etkili olabilir. Yanlış example bulunabilir. Telemetry rehber iyileştirmesine yön verir.

Documentation Feedback

Kullanıcı geri bildirimi doğrudan sinyal sağlar. Sayfa bazlı toplanabilir. Açık yorum alanı faydalıdır. Düşük puanlı içerikler review edilir. Yanıtlar düzenli analiz edilmelidir.

Stale Documentation Rate

Gerçek API ile doküman farkını ölçer. Contract test sonucu kullanılabilir. Drift sayısı takip edilir. Hedef sıfıra yakın olmalıdır. Otomasyon oranı düşürür.

API Adoption

Yeni consumer sayısı API kullanımını gösterir. Dokümantasyon tek etkileyen faktör değildir. Onboarding funnel ile birlikte incelenebilir. Drop-off noktaları bulunur. DX yatırımının etkisi daha iyi anlaşılır.

Swagger/OpenAPI CI/CD Pipeline

OpenAPI dosyasının CI/CD pipeline'a girmesi dokümantasyonu gerçek geliştirme sürecinin parçası yapar. Validation ve Spectral lint temel kaliteyi kontrol eder. Breaking change detection, example tests ve contract tests davranış uyumunu güçlendirir. Mock generation, documentation build ve SDK generation aynı canonical specification'dan otomatik tetiklenebilir. Deployment sonrasında API catalog da güncellenerek discovery bilgisi senkron tutulabilir.

OpenAPI Validation

Spec önce syntax ve semantic validation'dan geçer. Geçersiz belge reddedilir. Tool version pinlenir. Hata satırı gösterilir. Pipeline'ın ilk adımlarından biri olmalıdır.

Spectral Lint

Kurum style rules uygulanır. Naming ve owner kontrol edilir. Security kuralları çalışır. Error severity build'i etkiler. Rapor saklanabilir.

Breaking Change Detection

Base spec ile yeni spec karşılaştırılır. Kırıcı farklar listelenir. Approval kontrol edilir. Versioning ihtiyacı belirlenir. Consumer impact görünür olur.

Example Tests

Request ve response examples validate edilir. Stale örnek bulunur. PII scanner çalıştırılabilir. Kod snippet smoke test edilebilir. Doküman güvenilir kalır.

Contract Tests

Staging API gerçek contract ile test edilir. Schema ve status code doğrulanır. Header kontrol edilir. Drift build'i durdurabilir. Runtime uyumu korunur.

Mock Generation

Mock artifact spec'ten oluşturulur. Frontend pipeline kullanabilir. Example veriler güncel kalır. Version etiketi eklenir. Manual mock kopyası tutulmaz.

Documentation Build

Reference sayfası canonical spec'ten üretilir. Guide content ayrıca build edilir. Broken link kontrolü çalışır. Preview oluşturulur. Merge öncesi inceleme yapılabilir.

SDK Generation

SDK code generation otomatik çalışır. Generated kod test edilir. Package version belirlenir. Changelog hazırlanır. Registry release kontrollü yapılır.

Documentation Deployment

Başarılı build sonrası doküman yayınlanır. Cache invalidation yapılır. Version selector güncellenir. Public ve internal erişim ayrılır. Deployment sonucu izlenir.

Docs-as-Code Yaklaşımı

Docs-as-Code dokümantasyon dosyalarını uygulama koduna benzer geliştirme disiplinleriyle yönetir. OpenAPI specification Git içinde versionlanır. Branch, pull request, code review ve documentation review süreçleri aynı platformda uygulanabilir. CI/CD validation ve deployment görevlerini otomatikleştirir. Hatalı değişiklik gerektiğinde version history üzerinden geri alınabilir.

OpenAPI Dosyasını Git'te Tutmak

Git değişiklik tarihçesi sağlar. Author bilgisi görünür. Diff review yapılır. Tag ile release eşleştirilebilir. Canonical source açık hale gelir.

Branch

Spec değişikliği feature branch'te yapılabilir. Main doğrudan değiştirilmez. CI branch üzerinde çalışır. Preview üretilebilir. Merge sonrası canonical version güncellenir.

Pull Request

PR değişiklik tartışma alanıdır. Automated checks görünür. Consumer reviewer eklenebilir. Breaking impact gösterilebilir. Karar kaydı korunur.

Code Review

Teknik sözleşme de code review gerektirir. Naming incelenir. Schema tasarımı değerlendirilir. Security kontrol edilir. Otomasyonun bulamadığı sorunlar ele alınır.

Documentation Review

Teknik doğruluk yanında açıklama kalitesi incelenir. Examples okunur. Terminoloji kontrol edilir. Getting Started etkisi değerlendirilir. Technical writer katkısı değerli olabilir.

Version History

Git geçmişi contract değişimini gösterir. Ne zaman değiştiği görülür. Regression araştırılır. Changelog doğrulanabilir. Audit ihtiyacına yardımcı olur.

CI/CD

Pipeline validation çalıştırır. Lint ve test yapar. Preview üretir. Documentation deploy eder. Manuel işlem azalır.

Rollback

Hatalı doküman sürümü geri alınabilir. Ancak runtime API değişmişse yalnız spec rollback yeterli olmayabilir. Contract ve deployment eşlenmelidir. Release artifact versiyonlanmalıdır. Rollback prosedürü test edilmelidir.

Büyük OpenAPI Dosyaları Nasıl Yönetilir?

Büyük bir OpenAPI specification tek dosyada tutulduğunda merge conflict ve gezinme sorunları oluşabilir. Multi-file yaklaşım domain bazlı parçalama imkânı verir. Shared components ayrı dosyada tutulabilir ve external $ref ile kullanılabilir. Build aşamasında bundling yapılarak deployment için tek spec üretilebilir. Kaynak yapı geliştiricinin okunabilirliğine, dağıtım artifact'ı ise tooling uyumluluğuna göre tasarlanabilir.

Tek Dosya Yaklaşımı

Küçük API'de tek dosya basittir. Tooling uyumluluğu güçlüdür. Reference yolları kolaydır. Büyüdükçe conflict artar. Dosya gezinmesi zorlaşabilir.

Multi-File Specification

Büyük spec parçalara ayrılabilir. Domain dosyaları oluşturulur. Shared components paylaşılır. Build tool gerekir. Reference çözümü CI'da test edilmelidir.

Domain Bazlı Dosyalar

Users ve Orders ayrı tutulabilir. Ownership daha net olur. Ekipler daha az conflict yaşar. Ortak component dışarı alınabilir. Sınırlar domain tasarımıyla uyumlu olmalıdır.

Shared Components

Ortak schema merkezi dosyada bulunur. Error ve pagination paylaşılabilir. Domain modelleri gereksiz ortaklaştırılmamalıdır. Versioning gerekir. Circular ref kontrol edilmelidir.

External $ref

Dosyalar arası referans sağlar. Relative path tercih edilebilir. Remote dependency dikkatle kullanılmalıdır. Build ortamında çözülmelidir. Editor desteği test edilmelidir.

Bundling

Bundling çoklu dosyayı dağıtılabilir artifact'a toplar. Swagger UI için kolaylık sağlar. CI sırasında yapılabilir. Canonical kaynak multi-file kalabilir. Bundle deterministik olmalıdır.

Dereferencing

Dereferencing referansları inline genişletebilir. Bazı tooling bunu gerektirebilir. Dosya büyüyebilir. Circular model sorun yaratabilir. Sadece ihtiyaç olduğunda uygulanmalıdır.

Build Sırasında Tek Spec Üretmek

Kaynak dosyalar geliştirici dostu tutulur. CI bundle üretir. Validation bundled artifact üzerinde de çalışır. Version etiketi eklenebilir. Deployment aynı artifact'ı kullanır.

Merkezi OpenAPI Component Library

Merkezi component library sık tekrarlanan kurumsal modelleri bütün API'lerde ortaklaştırabilir. Error, pagination, Money, Address, Timestamp ve Correlation ID iyi adaylardır. Security schemes ve standard headers da merkezi tanımlanabilir. Library mutlaka versionlanmalı ve breaking değişiklikleri kontrollü yapılmalıdır. Her domain modelini merkezi library'ye taşımak ise gereksiz coupling yaratacağı için sınır dikkatle belirlenmelidir.

Error Schemas

Ortak error model tek yerde tutulur. Code ve message alanları standardize edilir. Correlation ID eklenir. Validation details desteklenir. Tüm API'ler aynı sözleşmeyi kullanabilir.

Pagination Schemas

Pagination metadata paylaşılabilir. nextCursor standardize edilir. hasMore aynı anlamı taşır. Client helper geliştirmek kolaylaşır. Farklı pagination ihtiyacı ayrı component olabilir.

Money

Money amount ve currency birlikte modellenmelidir. Precision kararı açık olmalıdır. Currency standardı belirtilmelidir. Floating point riski düşünülmelidir. Tüm servisler aynı modelden yararlanabilir.

Address

Address ortak görünse de domain farkları olabilir. Ülke ihtiyaçları değişebilir. Gereksiz rigid modelden kaçınılmalıdır. Gerçekten paylaşılan alanlar belirlenmelidir. PII hassasiyeti dikkate alınmalıdır.

Timestamp

Timestamp formatı merkezi belirlenebilir. UTC convention kullanılabilir. date-time schema paylaşılabilir. Description ortak olur. Consumer her API'de aynı formatı bekler.

Correlation ID

Correlation ID header veya schema component olabilir. Format standardize edilir. Logging entegrasyonu kolaylaşır. Support süreçleri iyileşir. Secret veya kişisel veri içermemelidir.

Security Schemes

Bearer ve OAuth tanımları merkezi tutulabilir. Scope isimleri domain'e göre değişebilir. Production credential bulunmaz. Tooling reuse desteklemelidir. Security review merkezi hale gelir.

Standard Headers

Request ID veya pagination header'ları paylaşılabilir. İsimler tek convention izler. Description tekrarı azalır. SDK behavior tutarlı olur. Gereksiz custom header üretimi engellenir.

Component Versioning

Shared library değişikliği birçok API'yi etkiler. Semantic versioning kullanılabilir. Breaking değişiklik major release olabilir. Consumer spec'ler kontrollü upgrade edilir. Dependency automation yardımcı olabilir.

OpenAPI Spec Güvenliği

OpenAPI specification teknik sistem hakkında önemli bilgi taşıdığı için güvenlik açısından değerlendirilmelidir. Internal endpoint, hostname, gerçek token veya API key public specification içine konulmamalıdır. Example veriler gerçek müşteri kaydı içermemelidir. Public ve private specification ayrımı build pipeline tarafından otomatik üretilebilir. Spec repository'si üzerinde secret scanning ve erişim kontrolü uygulanması güçlü bir güvenlik pratiğidir.

Internal Endpoint'leri Public Spec'e Koymamak

Internal endpoint dış tüketiciye gerekmez. Saldırı yüzeyi hakkında bilgi verebilir. Public build sırasında filtrelenmelidir. x-internal kullanılabilir. Authorization yine ayrı uygulanmalıdır.

Internal Hostname'ler

Hostname altyapı topolojisini gösterebilir. Public servers bölümünde bulunmamalıdır. Example metninde de sızabilir. CI regex kontrolü uygulanabilir. Internal spec ayrı erişimde tutulmalıdır.

Secret

Secret hiçbir zaman spec'e yazılmamalıdır. Placeholder kullanılmalıdır. Secret scanner repository'yi kontrol etmelidir. Sızıntı olursa rotation gerekir. Git geçmişi de temizlenmelidir.

API Key

Gerçek API key example olarak kullanılmamalıdır. test-key gibi açık placeholder seçilebilir. Try It Out kullanıcıdan değer almalıdır. Key loglarda maskelenmelidir. Public bundle içinde credential bulunmamalıdır.

Gerçek Token

Access token gerçek kullanıcı yetkisi taşıyabilir. Dokümana kopyalanmamalıdır. Screenshot içinde bile bulunmamalıdır. CI secret scanning yardımcı olur. Sızıntıda token revoke edilmelidir.

Gerçek Müşteri Verisi

Example payload gerçek müşteri içermemelidir. İsim ve adresler sentetik olmalıdır. Production response kopyalanmamalıdır. Sanitization pipeline uygulanabilir. KVKK gereksinimleri dikkate alınmalıdır.

Example Data Sanitization

Example veriler yayın öncesi taranmalıdır. E-posta ve telefon kontrol edilir. Token pattern aranır. Internal ID gerektiğinde değiştirilir. Manual review automation'ı tamamlar.

Public ve Private Specification Ayrımı

Aynı servis iki farklı görünüm üretebilir. Public spec yalnız dış contract'ı gösterir. Private spec internal operasyonları içerebilir. Build otomasyonu farkı uygular. Ayrım test edilmelidir.

API Dokümantasyonunda Hassas Veri

Dokümantasyon geliştiricilerin geniş erişimine açık olduğu için hassas veri bakımından production log kadar dikkat gerektirir. Gerçek kişisel veri, access token veya cookie değeri örneklerde kullanılmamalıdır. Internal ID bile bazı senaryolarda gereksiz bilgi açığa çıkarabilir. Sentetik ve sanitized examples tercih edilmelidir. KVKK yükümlülükleri dokümantasyon ve test verisi süreçlerinde de göz önünde bulundurulmalıdır.

Gerçek Kişisel Veri Kullanmamak

Gerçek kişi verisi dokümana kopyalanmamalıdır. Production örnekleri kullanılmamalıdır. Sentetik kayıt oluşturulmalıdır. Screenshot kontrol edilmelidir. Review checklist bunu içermelidir.

E-posta ve Telefon

Example için açıkça hayali değer kullanılmalıdır. Gerçek müşteri adresi kullanılmamalıdır. Telefon formatı yine gerçekçi olabilir. PII scanner pattern bulabilir. Gereksiz alan gösterilmemelidir.

Access Token

Access token secret kabul edilmelidir. Placeholder kullanılmalıdır. Token'ın prefix formatı gösterilebilir. Gerçek değerin tamamı yazılmamalıdır. Sızıntıda revoke işlemi yapılmalıdır.

Cookie

Session cookie kimlik bilgisi taşıyabilir. Screenshot ve request log örneklerinde maskelenmelidir. SameSite davranışı açıklanabilir. Gerçek session değeri kullanılmamalıdır. Public guide güvenli örnek kullanmalıdır.

Internal ID

Internal ID bazen sistem topolojisi hakkında bilgi verebilir. Public example'da gerekli değilse kullanılmamalıdır. Sentetik ID tercih edilir. Public identifier modeli ayrı olabilir. Data exposure review yapılmalıdır.

KVKK

KVKK kişisel verinin işlenmesini ve korunmasını ilgilendirir. Dokümantasyon da veri yayma kanalı olabilir. Gerçek kişi verisi kullanımından kaçınılmalıdır. Kurum hukuk ve güvenlik politikaları izlenmelidir. Veri minimizasyonu uygulanmalıdır.

Sanitized Examples

Sanitized example gerçek yapıyı korur. Hassas değerleri sentetik verilerle değiştirir. Schema geçerliliği sürdürülür. Otomatik tarama yapılabilir. Dokümana güvenle eklenebilir.

Swagger UI CORS Problemleri

Swagger UI browser içinde çalıştığı için Try It Out request'leri CORS kurallarına tabidir. Doküman farklı origin'den API'ye istek gönderiyorsa server uygun Access-Control-Allow-Origin politikasına sahip olmalıdır. Authentication header gibi değerlerin de izin verilen header listesinde bulunması gerekebilir. Sırf Swagger UI çalışsın diye production CORS politikasını tüm origin'lere açmak güvenli bir çözüm değildir. Staging ortamında kontrollü origin tanımıyla test etmek daha doğru yaklaşımdır.

Browser-Based Try It Out

Request browser güvenlik modelinden geçer. CORS uygulanır. Server response header göndermelidir. CLI ile çalışan request browser'da başarısız olabilir. Bu fark dokümanda açıklanabilir.

Origin

Origin scheme, host ve port kombinasyonunu temsil eder. Swagger UI ile API farklı origin olabilir. Server izin politikasını belirler. Wildcard dikkatle kullanılmalıdır. Credential request'lerde ek kısıtlar vardır.

Access-Control-Allow-Origin

Bu header izin verilen origin'i belirtir. Production'da gereksiz wildcard kullanımından kaçınılmalıdır. Portal domain'i allow list'e eklenebilir. Environment bazlı config yapılabilir. Güvenlik testi uygulanmalıdır.

Authentication Header

Authorization header preflight kontrolüne takılabilir. Allowed headers listesi doğru olmalıdır. Credential policy değerlendirilmelidir. Token browser içinde güvenli tutulmalıdır. CORS auth yerine geçmez.

Staging CORS

Staging Swagger UI için uygun origin izinleri verilebilir. Test akışı production'a benzer tutulur. Gerekli header'lar doğrulanır. Wildcard yerine belirli domain kullanılabilir. Sorun production öncesi yakalanır.

Production CORS'u Gereksiz Genişletmemek

CORS kolaylık için gevşetilmemelidir. Gereken origin'ler açıkça tanımlanmalıdır. Credential desteği dikkatle yapılmalıdır. Security review uygulanmalıdır. Swagger UI ihtiyacı tüm API güvenlik politikasını belirlememelidir.

OpenAPI ile AI ve Agent Entegrasyonu

OpenAPI'nin machine-readable yapısı API'lerin otomatik araçlar tarafından keşfedilmesi ve çağrılması için de değerlidir. operationId ve schema description kalitesi burada daha da önemli hale gelir. Belirsiz operation adı yalnız geliştiriciyi değil, API'yi programatik olarak yorumlayan araçları da zorlaştırır. Tool calling senaryolarında yalnız gerekli endpoint'lerin erişime açılması ve güçlü authorization uygulanması gerekir. Makine tüketimine hazır dokümantasyon yine aynı temel kalite prensiplerine dayanır: açık sözleşme, sınırlı yetki ve doğru schema.

Machine-Readable Tool Definition

Structured contract otomatik sistem tarafından parse edilebilir. Parameter tipleri anlaşılır. Required alanlar görülür. operationId action adı olabilir. Description semantik bağlam sağlar.

API'yi AI Araçlarına Tanıtmak

OpenAPI belirli entegrasyonlarda tool tanımı kaynağı olabilir. Tüm endpoint'ler otomatik açılmamalıdır. Read-only subset tercih edilebilir. Authentication sınırı korunmalıdır. Audit log tutulmalıdır.

operationId Kalitesinin Önemi

operationId operation niyetini açıkça göstermelidir. listUsers gibi isimler anlaşılırdır. Generic execute1 isimleri sorun yaratır. Stable naming gereklidir. SDK ve agent entegrasyonu birlikte fayda görür.

Schema Description Kalitesinin Önemi

Field adı her zaman yeterli anlam taşımaz. Description iş kuralını açıklar. Unit belirtilmelidir. Enum anlamı yazılmalıdır. Belirsiz schema otomatik kullanım riskini artırır.

Tool Calling

Tool calling API operation'ını programatik eyleme dönüştürebilir. Parameter validation uygulanmalıdır. Authorization server tarafında korunmalıdır. Side-effect operation'ları özel kontrol gerektirir. İnsan onayı gereken işlemler ayrılabilir.

AI Agent'ın Kullanabileceği Endpoint'leri Sınırlandırmak

Least privilege uygulanmalıdır. Gereksiz DELETE operation açılmamalıdır. Scope sınırlı tutulmalıdır. Rate limit kullanılmalıdır. Audit ve revocation desteği bulunmalıdır.

API Dokümantasyonunun Makine Tüketimine Hazır Olması

Schema tam olmalıdır. operationId benzersiz olmalıdır. Description gerçek davranışı anlatmalıdır. Error modeli öngörülebilir olmalıdır. Aynı kalite insan consumer'a da fayda sağlar.

Swagger/OpenAPI Entegrasyonu: Popüler Programlama Dilleri

OpenAPI programlama dilinden bağımsız bir HTTP API sözleşmesi olduğu için farklı backend ekosistemleriyle birlikte kullanılabilir. Python, TypeScript, Java, C#, Go ve PHP tarafında code-first veya design-first entegrasyonları bulunur. Framework seçimi spec kalitesinin yerine geçmez. Generated OpenAPI mutlaka lint ve contract test süreçlerinden geçirilmelidir. Dil farkından bağımsız olarak naming, errors, security ve versioning standardı ortak tutulabilir.

Python

Python API geliştirmede yaygın bir seçenektir. Type hint'lerden schema üretilebilir. Design-first client generation da yapılabilir. Validation davranışı test edilmelidir. OpenAPI contract framework'ten bağımsız düşünülmelidir.

FastAPI

FastAPI type metadata üzerinden OpenAPI üretebilir. Request ve response modelleri tanımlanabilir. Swagger UI entegrasyonu yaygındır. Generated spec CI'a alınmalıdır. Production docs erişimi kontrollü yapılmalıdır.

Django / DRF

Django ve DRF ekosisteminde schema generation çözümleri kullanılabilir. Serializer metadata'sı spec'e dönüşebilir. Custom behavior ayrıca belgelenmelidir. Generated output lint edilmelidir. Legacy endpoint'ler kademeli standardize edilebilir.

Flask

Flask daha minimal bir yapı sunar. OpenAPI entegrasyonu ek araçlarla yapılabilir. Annotation veya design-first yaklaşım uygulanabilir. Route ile spec drift riski kontrol edilmelidir. Contract test faydalıdır.

TypeScript / JavaScript

TypeScript güçlü type sistemiyle schema üretimine yardımcı olabilir. JavaScript projelerinde de OpenAPI kullanılabilir. Runtime validation ayrıca düşünülmelidir. SDK generation frontend entegrasyonunu kolaylaştırabilir. Specification framework'ten bağımsız tutulmalıdır.

NestJS

NestJS decorator metadata üzerinden OpenAPI üretebilir. DTO modelleri schema'ya dönüşebilir. operationId standardı ayrıca kontrol edilmelidir. Generated spec CI'da lint edilmelidir. Production docs güvenliği yapılandırılmalıdır.

Express

Express daha serbest tasarım sunar. Spec manuel veya ek tooling ile üretilebilir. Route drift riski daha yüksektir. Runtime validation faydalı olabilir. Contract-first yaklaşım güçlü bir seçenek olabilir.

Java

Java kurumsal API sistemlerinde yaygın kullanılır. Annotation tabanlı generation uygulanabilir. Design-first stub generation da mümkündür. Type mapping dikkatle test edilmelidir. API standardı framework bağımsız olmalıdır.

Spring Boot

Spring Boot uygulamalarında OpenAPI entegrasyonu yapılabilir. Controller metadata spec'e dönüştürülebilir. Security tanımlarının doğru üretildiği kontrol edilmelidir. Generated output versionlanabilir. Contract test eklemek faydalıdır.

C# / .NET

.NET ekosisteminde OpenAPI generation yaygın kullanılır. Controller metadata specification oluşturabilir. Nullable model dikkat gerektirir. SDK generation da yapılabilir. CI lint tüm servislerde ortak tutulmalıdır.

ASP.NET Core

ASP.NET Core endpoint metadata üzerinden OpenAPI oluşturabilir. Swagger UI development ortamında sunulabilir. Production erişimi ayrıca kontrol edilir. Schema naming standardı uygulanmalıdır. Generated spec breaking diff'e sokulmalıdır.

Go

Go API'lerinde design-first ve code-first seçenekleri vardır. Struct tag ve generator araçları kullanılabilir. Optional alan davranışı dikkatle modellenmelidir. Generated server interface faydalı olabilir. Contract test gerçek response'u doğrulamalıdır.

PHP

PHP API'lerinde OpenAPI annotation veya attribute ile üretilebilir. Manuel spec de kullanılabilir. Framework bağımsız contract yönetimi mümkündür. Lint pipeline eklenmelidir. Swagger UI yalnız reference katmanı olarak görülmelidir.

Laravel

Laravel uygulamasında OpenAPI entegrasyonu ek tooling ile yapılabilir. Request validation contract'a yansıtılmalıdır. Resource response modelleri belgelenmelidir. Generated spec review edilmelidir. Security scheme doğru tanımlanmalıdır.

API Geliştirme İçin En İyi Programlama Dili Hangisidir?

API geliştirme için herkes adına tek bir en iyi programlama dili yoktur. Python hızlı geliştirme, TypeScript full-stack type paylaşımı, Java ve C# kurumsal ekosistem, Go ise sade concurrency modeli gibi farklı avantajlar sunar. PHP de güçlü web ekosistemiyle birçok API projesinde kullanılabilir. REST ve OpenAPI sözleşmesi bu dillerden bağımsızdır. Uzun vadede dil seçiminden daha kritik konu açık, test edilebilir ve geriye uyumlu bir API contract üretmektir.

Python

Python okunabilir syntax sunar. API framework seçenekleri geniştir. Hızlı prototip geliştirilebilir. Type validation araçları kullanılabilir. Performans ihtiyacı ölçülerek karar verilmelidir.

TypeScript

TypeScript frontend ve backend type deneyimini yakınlaştırır. Node ekosistemi geniştir. Async I/O senaryolarında pratiktir. Runtime validation yine gereklidir. OpenAPI type generation ile desteklenebilir.

Java

Java olgun kurumsal ekosisteme sahiptir. Strong typing avantajı sunar. Framework desteği geniştir. Operasyonel araçlar güçlüdür. Ekip deneyimi seçimde önemli faktördür.

C#

C# modern dil özellikleri sunar. .NET ekosistemi güçlüdür. Web API geliştirme araçları gelişmiştir. Enterprise sistemlerle uyum sağlar. Ekip becerisi yine belirleyicidir.

Go

Go sade deployment modeli sunar. Concurrency desteği güçlüdür. Derlenen binary operasyonu kolaylaştırabilir. Ekosistem farklı trade-off'lara sahiptir. API contract kalitesi dilden bağımsızdır.

PHP

PHP web geliştirmede yaygın kullanılır. Framework ekosistemi güçlüdür. Hızlı geliştirme sağlayabilir. Modern type özellikleri mevcuttur. OpenAPI entegrasyonu tooling ile yapılabilir.

REST ve OpenAPI'nin Programlama Dilinden Bağımsız Olması

OpenAPI HTTP contract'ını tanımlar. Backend Python olabilir. Consumer Java kullanabilir. Aynı spec iki tarafı buluşturur. Bu bağımsızlık standardın önemli avantajıdır.

Dil Seçiminden Daha Önemli Olan API Contract Kalitesi

Kötü contract iyi framework ile düzelmez. Naming ve error modeli önemlidir. Versioning düşünülmelidir. Security açık tanımlanmalıdır. Tooling bu kaliteyi otomatik korumalıdır.

Open Source ve İşbirliği ile API Standardizasyonu

OpenAPI ekosisteminin güçlü yönlerinden biri açık standartlar ve açık kaynak araçlar etrafında gelişmesidir. Specification çalışmaları, Swagger UI, Swagger Editor, OpenAPI Generator ve Spectral gibi araçlar farklı kullanım ihtiyaçlarını destekler. Ekipler açık API style guide örneklerinden fikir alabilir. Issue ve pull request süreçleriyle kullanılan tooling'e katkı sağlamak mümkündür. Kurum içinde de ortak ruleset geliştirme yaklaşımı benzer işbirliği kültürünü destekler.

OpenAPI Initiative

OpenAPI standardının geliştirilmesini destekleyen yapıdır. Specification açık biçimde yayımlanır. Sürüm değişiklikleri izlenebilir. Kurumlar standardı araç bağımsız kullanabilir. Teknik ekiplerin resmi specification'ı referans alması önemlidir.

Swagger UI

Swagger UI OpenAPI reference'ı görselleştirir. Açık kaynak kullanım seçeneği vardır. Customization yapılabilir. Version compatibility kontrol edilmelidir. Spec doğruluğu UI'dan daha önemlidir.

Swagger Editor

Editor spec yazımını kolaylaştırır. Syntax feedback verir. Preview sağlar. Design-first süreçte kullanılabilir. Kurumsal lint ayrıca eklenmelidir.

OpenAPI Generator

Generator farklı dillerde SDK ve stub üretebilir. Template özelleştirilebilir. Upgrade etkisi test edilmelidir. Generated kod manuel kaynak olmamalıdır. operationId kalitesi önemlidir.

Spectral

Spectral kurumsal lint için kullanılabilir. Custom ruleset destekler. IDE ve CI entegrasyonu yapılabilir. Policy as code modeline uygundur. Ruleset versionlanmalıdır.

Open Source API Style Guide'ları

Açık örnekler fikir vermek için değerlidir. Kurumun ihtiyaçları birebir aynı olmayabilir. Kurallar körlemesine kopyalanmamalıdır. Gerekçe anlaşılmalıdır. Kendi consumer deneyiminize göre uyarlanmalıdır.

GitHub Issue

Issue teknik problem veya öneriyi kayıt altına alır. Açık kaynak projelerde iletişim sağlar. Reproducible example eklenmelidir. Version bilgisi belirtilmelidir. Topluluk katkısı kolaylaşır.

Pull Request

Pull request doğrudan katkı sağlar. Kod veya doküman düzeltilebilir. Review sürecinden geçer. Testler çalışır. Ortak geliştirme kültürünü güçlendirir.

Ortak Ruleset Geliştirmek

Kurum ekipleri ruleset'e birlikte katkı verebilir. Backend ve consumer görüşü alınır. Security kuralları eklenir. Her değişiklik test edilir. Ruleset ortak teknik sözleşmeye dönüşür.

Kurum İçinde API Standardını Ekip Olarak Geliştirmek

API standardı yalnız platform ekibinin kapalı kapılar ardında yazdığı bir doküman olmamalıdır. Backend, frontend, mobil, security ve technical writer ekipleri farklı sorunları görür. API consumer'ların geri bildirimi hangi kuralların gerçekten geliştirici deneyimini iyileştirdiğini ortaya çıkarır. RFC süreci önemli değişikliklerin tartışılmasını sağlar. Style guide'ın kendisi de versionlanmalı ve kurallar değiştiğinde migration yaklaşımı sunulmalıdır.

Backend Ekipleri

Backend ekipleri implementation gerçekliğini getirir. Status code ve schema kararlarına katkı verir. Performance kısıtlarını açıklar. Ruleset'in uygulanabilirliğini test eder. Standart sahipliğini paylaşır.

Frontend ve Mobile Ekipleri

Consumer ekipler API ergonomisini doğrudan yaşar. Nullable field sorunlarını görür. Pagination deneyimini değerlendirir. SDK naming hakkında feedback verir. Standardın yalnız server bakışıyla şekillenmesini önler.

Platform Engineering

Platform ekibi tooling ve pipeline sağlar. Starter repository hazırlayabilir. Ruleset dağıtır. Catalog altyapısı kurar. Self-service governance oluşturur.

Security

Security authentication ve data exposure kurallarına katkı verir. Secret scanning belirler. Public spec politikasını oluşturur. OAuth scope standardını inceler. Risk bazlı approval tanımlar.

Technical Writers

Technical writer içerik yapısını iyileştirir. Terminoloji tutarlılığı sağlar. Getting Started akışını değerlendirir. Example okunabilirliğini artırır. Developer portal bilgi mimarisine katkı verir.

API Consumers

Consumer gerçek kullanım sorununu gösterir. Eksik hata açıklamasını fark eder. Authentication adımlarını test eder. Breaking change etkisini açıklar. Standardın pratik değerini doğrular.

RFC Süreci

RFC önemli standard değişikliğini tartışmaya açar. Problem açıkça yazılır. Alternatifler değerlendirilir. Karar kaydedilir. Ekipler değişikliğe hazırlanır.

Style Guide Değişikliklerini Versionlamak

Style guide da yaşayan bir üründür. Version etiketi kullanılabilir. Breaking governance değişikliği duyurulur. Ruleset sürümüyle eşlenir. Repository'ler kontrollü upgrade edilir.

Yazılımcı Olmak İçin Ne Yapmalı? API Geliştirme Yol Haritası

API geliştirmeyi öğrenmek isteyen biri için yalnız Swagger UI kullanmayı bilmek yeterli değildir. Önce HTTP, REST ve JSON gibi temel kavramları öğrenmek gerekir. Ardından bir programlama dili, authentication, OpenAPI, testing, Git ve CI/CD becerileri eklenebilir. Güvenlik bilgisi gerçek production API geliştirmek için zorunlu hale gelir. En iyi öğrenme yöntemi küçük fakat gerçek kullanıcıya açık bir API projesini tasarlamak, dokümante etmek, test etmek ve yayınlamaktır.

HTTP Öğrenmek

Method ve status code öğrenilmelidir. Header davranışı anlaşılmalıdır. Cache ve content negotiation bilinmelidir. Authentication temel HTTP bilgisini kullanır. API tasarımının temeli buradadır.

REST Temelleri

Resource kavramı öğrenilmelidir. URI tasarımı anlaşılmalıdır. Method semantiği uygulanmalıdır. Stateless yaklaşım incelenmelidir. Kurallar ezberden çok gerekçesiyle öğrenilmelidir.

Bir Programlama Dili

Python veya TypeScript gibi bir dil seçilebilir. Temel syntax öğrenilir. Web framework kullanılır. Database entegrasyonu yapılır. Sonra aynı contract başka dillerden tüketilebilir.

JSON

JSON API veri formatında yaygındır. Object ve array yapısı öğrenilmelidir. Null davranışı anlaşılmalıdır. Serialization hataları test edilmelidir. Schema ile ilişkisi kurulmalıdır.

API Authentication

API key ve bearer token öğrenilmelidir. OAuth temelleri incelenmelidir. Authorization ile authentication ayrılmalıdır. Secret management anlaşılmalıdır. HTTPS zorunluluğu bilinmelidir.

OpenAPI

Specification yapısı öğrenilmelidir. paths ve components incelenmelidir. Schema yazılmalıdır. Security tanımı denenmelidir. Küçük bir API baştan sona belgelenmelidir.

Swagger UI

OpenAPI dosyası UI içinde açılmalıdır. Try It Out denenmelidir. Authentication yapılandırılmalıdır. Tag organizasyonu görülmelidir. UI ile specification farkı anlaşılmalıdır.

API Testing

Unit ve integration test öğrenilmelidir. Contract test eklenmelidir. Error scenario yazılmalıdır. Load test temel seviyede görülmelidir. Otomasyon CI'a bağlanmalıdır.

Git

Version control geliştirme pratiğinin temelidir. Branch kullanılır. Pull request açılır. Code review öğrenilir. OpenAPI dosyası da aynı süreçten geçer.

CI/CD

Pipeline otomatik kontrol sağlar. Test çalıştırılır. Lint uygulanır. Artifact build edilir. Deployment kontrollü yapılır.

API Security

Input validation önemlidir. Authentication doğru uygulanmalıdır. Authorization resource seviyesinde kontrol edilmelidir. Rate limit eklenmelidir. Secret loglanmamalıdır.

Gerçek Bir Public API Geliştirmek

Gerçek proje öğrenmeyi hızlandırır. Consumer feedback alınır. Dokümantasyon eksikleri görülür. Versioning ihtiyacı anlaşılır. Operasyon ve güvenlik deneyimi kazanılır.

Diyarbakır Yazılım Topluluğu ile API Geliştirme ve Standardizasyon

API geliştirmeyi yalnız okuyarak değil, birlikte üretip review ederek öğrenmek çok daha kalıcı sonuç verir. Diyarbakır Yazılım Topluluğu içinde backend geliştirme, test, REST tasarımı ve açık kaynak odaklı çalışmalar bu deneyimi destekleyebilir. Topluluğun yürüttüğü projeleri incelemek için https://www.diyarbakiryazilim.com.tr/projects adresine göz atabilirsiniz. Backend test yaklaşımını API contract testing ile birlikte değerlendirmek isteyenler https://www.diyarbakiryazilim.com.tr/posts/backend-test-stratejileri-birim-unit-ve-entegrasyon-testleri içeriğinden de yararlanabilir. Topluluk hakkında genel bilgi için https://www.diyarbakiryazilim.com.tr/about adresi kullanılabilir.

Diyarbakır Yazılım Topluluğu İçinde Backend Çalışmaları

Backend çalışmaları gerçek API problemlerini tartışmak için iyi ortam sağlar. HTTP tasarımı birlikte incelenebilir. Code review yapılabilir. Contract test örnekleri geliştirilebilir. Deneyim ekip içinde paylaşılabilir.

Swagger ve OpenAPI Workshopları

Workshop formatı specification öğrenimini hızlandırır. Katılımcı gerçek OpenAPI dosyası yazar. Swagger UI çıktısını görür. Lint hatalarını düzeltir. CI entegrasyonu uygulamalı gösterilebilir.

REST API Design Atölyeleri

Atölyede resource modeli birlikte tasarlanabilir. Endpoint naming tartışılabilir. Error contract oluşturulabilir. Pagination örneği yapılabilir. Consumer bakışıyla review gerçekleştirilebilir.

Open Source ve İşbirliği Çalışmaları

Ortak repository ekip çalışmasını öğretir. Issue açılır. Pull request hazırlanır. Review kültürü gelişir. API standardı gerçek proje üzerinde denenebilir.

Ortak API Style Guide Oluşturmak

Topluluk ortak style guide hazırlayabilir. Naming ve errors tanımlanabilir. Örnek OpenAPI eklenebilir. RFC ile kurallar geliştirilebilir. Rehber yeni geliştiricilere başlangıç sağlayabilir.

Spectral Ruleset Geliştirmek

Style guide kuralları Spectral ruleset'e dönüştürülebilir. operationId kontrol edilir. Error schema zorunlu tutulabilir. Test fixture hazırlanır. Ruleset açık kaynak olarak paylaşılabilir.

Diyarbakır'daki En İyi Yazılımcılarla Teknik Deneyim Paylaşımı

Teknik deneyim paylaşımı farklı yaklaşımları görmeyi sağlar. Backend geliştiriciler gerçek sorunlarını anlatabilir. API consumer'ları feedback verebilir. Review kültürü güçlenir. Birlikte üretmek yalnız teorik öğrenmenin ötesine geçer.

Ortak Proje Fikirleri

API standardizasyonu uygulamalı proje üretmeye uygundur. Küçük ekipler farklı bileşenleri üstlenebilir. Contract ortak merkez olur. CI süreçleri gerçek ortamda denenir. Sonuç topluluk için tekrar kullanılabilir kaynak haline gelir.

Open Source API

Topluluk ortak public API geliştirebilir. OpenAPI contract önce hazırlanabilir. Contribution guide yazılabilir. Contract tests eklenebilir. API gerçek consumer'larla denenebilir.

API Developer Portal

Developer portal API'leri tek yerde gösterebilir. Getting Started hazırlanabilir. Swagger UI reference entegre edilir. Changelog eklenir. Search deneyimi test edilebilir.

API Style Guide

Ortak style guide eğitim kaynağı olabilir. Naming örnekleri içerir. Error modeli açıklar. Versioning politikası gösterir. Yeni projeler aynı temelden başlayabilir.

Swagger/OpenAPI Starter Kit

Starter kit örnek spec içerebilir. Spectral config eklenir. CI workflow bulunur. Swagger UI deployment örneği sunulur. Yeni API projesi birkaç dakikada başlatılabilir.

Uçtan Uca Örnek: Standart Bir OpenAPI Specification Oluşturmak

Uçtan uca örnek hazırlarken metadata'dan authentication'a kadar tüm contract birlikte düşünülmelidir. Yalnız GET /users operation'ını yazmak gerçek standartlaşmayı göstermez. API metadata, servers, user resource, request ve response schemas, common errors, pagination, tags ve operationId aynı örnekte yer almalıdır. Example veriler schema ile uyumlu olmalıdır. Böyle bir starter specification yeni servislerin aynı standardı benimsemesini ciddi biçimde kolaylaştırır.

API Metadata

info alanı title ve version içerir. Contact eklenir. API owner tanımlanır. Description kapsamı açıklar. Metadata linter ile doğrulanır.

Server

Staging ve production server ayrılır. HTTPS kullanılır. Internal host public spec'e girmez. Description ortamı belirtir. Try It Out staging'i hedefleyebilir.

User Resource

User schema açık alanlar içerir. ID formatı belirlenir. Tarihler standarda uyar. PII alanları dikkatle modellenir. Create ve response modeli gerektiğinde ayrılır.

GET /users

Liste operation'ı pagination kullanır. Filter parametreleri tanımlanır. listUsers operationId verilir. Success ve error response yazılır. Tag Users olur.

POST /users

Create operation request body alır. Required alanlar belirtilir. createUser operationId kullanılır. 201 response tanımlanır. Conflict error belgelenir.

GET /users/{id}

Path parameter required olur. ID formatı gösterilir. getUser operationId kullanılır. 404 response bulunur. User schema reuse edilir.

Request Schema

CreateUserRequest ayrı component olabilir. Server-generated alan içermez. Required field açıkça belirtilir. Validation kuralları eklenir. Example test edilir.

Response Schema

UserResponse public alanları içerir. createdAt date-time kullanır. Secret field bulunmaz. Required alanlar stable tutulur. $ref ile reuse edilir.

Standard Error Schema

Error component code ve message taşır. Details optional olabilir. Correlation ID bulunur. Validation errors desteklenebilir. Tüm operation'lar aynı modeli kullanır.

Authentication

Bearer security scheme tanımlanır. Global requirement uygulanabilir. Public endpoint gerekirse override edilir. Gerçek token yazılmaz. Scope ihtiyacı açıklanır.

Pagination

limit ve cursor parametreleri reusable olabilir. nextCursor response metadata'da bulunur. hasMore eklenir. Maximum limit belirtilir. Tüm liste endpoint'leri aynı modeli kullanır.

Examples

Request ve response example eklenir. Error example bulunur. Gerçek kişi verisi kullanılmaz. Schema validation çalıştırılır. Mock server bunlardan yararlanabilir.

Tags

Users tag resource grubunu tanımlar. Description eklenebilir. Operation tek ana tag kullanır. Naming standardı izlenir. UI daha düzenli görünür.

operationId

listUsers ve getUser gibi isimler kullanılır. Benzersizlik kontrol edilir. SDK method kalitesi artar. Değişiklik breaking etki yaratabilir. Linter pattern uygular.

Uçtan Uca Örnek: Kurumsal API Governance Pipeline

Kurumsal governance pipeline'ının amacı geliştiricinin işini yavaşlatmadan kalite standardını otomatik uygulamaktır. OpenAPI dosyası Git repository içinde versionlanır ve IDE linting daha yazım aşamasında feedback verir. Pull request sonrasında Spectral, breaking-change detection, contract tests ve security checks çalışır. Documentation preview reviewer'ın gerçek çıktıyı görmesini sağlar. Merge sonrası Swagger UI deployment, SDK generation ve API catalog update otomatik tetiklenebilir.

OpenAPI Dosyasını Git'e Ekleme

Canonical spec repository'de tutulur. Code owner tanımlanır. History saklanır. Branch policy uygulanır. Build artifact kaynağı burası olur.

Developer'ın Değişiklik Yapması

Developer branch açar. Spec'i günceller. Example değiştirir. Changelog ekler. Lokal lint çalıştırır.

IDE Linting

Kurumsal ruleset otomatik yüklenir. Hata anında görünür. Naming düzeltilebilir. Missing owner fark edilir. PR öncesi kalite artar.

Pull Request

PR contract diff'i gösterir. Review tetiklenir. Checks otomatik başlar. Consumer etkisi tartışılır. Karar kayıt altında kalır.

Spectral Rules

Style guide kod olarak uygulanır. operationId kontrol edilir. Error schema doğrulanır. Security standardı denetlenir. Error build'i durdurabilir.

Breaking-Change Detection

Base spec ile yeni spec karşılaştırılır. Kırıcı değişiklik listelenir. Approval gereksinimi kontrol edilir. Versioning önerilebilir. Merge gerektiğinde engellenir.

Contract Tests

Staging API test edilir. Response schema doğrulanır. Header kontrol edilir. Error case çalıştırılır. Spec drift yakalanır.

Security Review

Internal host sızıntısı kontrol edilir. Security scheme incelenir. Secret scan çalıştırılır. Riskli operation manuel review alabilir. Public exposure değerlendirilir.

Documentation Preview

PR için geçici UI oluşturulabilir. Reviewer final reference görünümünü görür. Example okunur. Navigation test edilir. Merge öncesi içerik problemi bulunur.

Merge

Tüm kontroller geçince main güncellenir. Canonical contract değişir. Release metadata hazırlanır. Deployment workflow başlar. Audit kaydı korunur.

Swagger UI Deployment

Yeni spec UI'a yayınlanır. Version selector güncellenir. Cache yenilenir. Access policy korunur. Production Try It Out ayarı kontrol edilir.

SDK Generation

Client code otomatik üretilir. Testler çalışır. Package version belirlenir. Registry'ye yayınlanır. Changelog API release ile eşlenir.

API Catalog Güncellemesi

Catalog yeni version'ı alır. Owner doğrulanır. Documentation linki güncellenir. Lifecycle state yansıtılır. Consumer discovery güncel kalır.

Swagger/OpenAPI Kullanımında Sık Yapılan Hatalar

Swagger ve OpenAPI projelerinde en yaygın hata specification'ı yalnızca güzel bir dokümantasyon ekranı üretmek için kullanmaktır. Description ve examples boş bırakıldığında UI teknik olarak çalışsa da developer experience düşer. Sadece 200 response belgelemek ve error formatını her endpoint'te farklı yapmak entegrasyon maliyetini artırır. Versioning, breaking change detection ve security kontrollerinin eksikliği daha büyük production sorunlarına yol açabilir. En güvenli yaklaşım specification'ı yaşayan contract olarak yönetmektir.

Swagger ile OpenAPI'yi Aynı Şey Sanmak

Bu terminoloji confusion yaratır. OpenAPI specification'dır. Swagger araç adlarında kullanılır. Sürüm konuşurken hangi parça olduğu belirtilmelidir. Kurum dokümanı doğru terimi kullanmalıdır.

Eski OpenAPI Sürümünü Körlemesine Kullanmak

Legacy template yeni projeye kopyalanmamalıdır. Güncel specification incelenmelidir. Tooling compatibility test edilir. Migration maliyeti değerlendirilir. Bilinçli version kararı verilmelidir.

Spec'i Yalnızca Doküman Üretmek İçin Kullanmak

Bu yaklaşım büyük potansiyeli kaçırır. Spec test input'u olabilir. SDK üretebilir. Breaking diff çalıştırabilir. Governance kaynağı haline gelebilir.

Description Alanlarını Boş Bırakmak

Alan adı her zaman yeterli değildir. Business semantiği kaybolur. AI ve SDK tooling bağlam bulamaz. Developer soru sormak zorunda kalır. Kritik alanlar açıklanmalıdır.

Example Eklememek

Schema tek başına kullanım örneği sağlamaz. Developer payload'ı tahmin eder. Mock server zayıf kalır. Onboarding süresi uzar. Example coverage ölçülmelidir.

Sadece 200 Response Dokümante Etmek

Gerçek API hata üretebilir. Consumer 401 davranışını bilmelidir. Validation error schema gerekir. 429 retry davranışı önemlidir. Hata cevapları birinci sınıf contract olmalıdır.

Error Formatlarını Endpoint Bazında Değiştirmek

Tutarsız error client kodunu büyütür. Her endpoint ayrı parser gerektirir. Support zorlaşır. Common error schema kullanılmalıdır. Domain code farklılaşabilir fakat yapı aynı kalmalıdır.

operationId Standardı Olmaması

Generator kötü method isimleri üretir. Duplicate değer oluşabilir. SDK deneyimi düşer. Diff etkisi takip edilemez. Linter naming'i zorunlu kılmalıdır.

$ref Kullanmadan Schema Kopyalamak

Kopya schema zamanla ayrışır. Bakım maliyeti artar. Error modeli tutarsızlaşır. Reusable components kullanılmalıdır. Aşırı abstraction'dan yine kaçınılmalıdır.

Versioning Stratejisi Olmaması

Breaking change geldiğinde ekip hazırlıksız kalır. Consumer migration süresi bilinmez. Eski endpoint aniden kapanabilir. Version ve deprecation policy önceden yazılmalıdır. Changelog bunu desteklemelidir.

Dokümantasyonu Manuel Güncellemek

Manuel süreç kolay unutulur. Spec drift oluşur. Code release dokümandan önce gider. Pipeline automation uygulanmalıdır. Single source of truth kurulmalıdır.

Breaking Change Detection Yapmamak

Küçük schema değişikliği consumer'ı bozabilir. Reviewer etkisini fark etmeyebilir. Structural diff otomatik çalışmalıdır. Critical API'lerde merge gate olmalıdır. Approved exception kaydedilmelidir.

Swagger UI'yi Kontrolsüz Production'a Açmak

Internal endpoint görünebilir. Try It Out write request gönderebilir. Credential riski oluşur. Access control uygulanmalıdır. Public ve internal UI ayrılmalıdır.

Gerçek Secret'ları Example İçinde Yayınlamak

Bu ciddi güvenlik problemidir. Placeholder kullanılmalıdır. Secret scanner devreye alınmalıdır. Sızıntı görülürse credential rotate edilmelidir. Repository history de kontrol edilmelidir.

Production Öncesi OpenAPI Kontrol Listesi

Production öncesi OpenAPI kontrolü yalnız syntax validation ile bitmemelidir. Specification sürümü tooling ile uyumlu olmalı, metadata ve ownership eksiksiz bulunmalıdır. Tüm operation'ların parameters, examples, errors ve authentication bilgileri gözden geçirilmelidir. Spectral, breaking change ve contract tests pipeline üzerinde başarılı olmalıdır. Son aşamada gerçek secret, PII, Swagger UI erişimi ve changelog durumu ayrıca kontrol edilmelidir.

OpenAPI Dosyası Syntax Olarak Geçerli mi?

Belge parser tarafından açılabilmelidir. YAML hatası bulunmamalıdır. OpenAPI validator çalışmalıdır. CI otomatik kontrol etmelidir. Manuel kontrol yeterli değildir.

Kullanılan OAS Sürümü Tooling ile Uyumlu mu?

UI sürümü test edilmelidir. Generator desteği doğrulanmalıdır. Gateway behavior kontrol edilmelidir. Linter uyumu görülmelidir. Ortak compatibility matrix tutulabilir.

info Alanları Eksiksiz mi?

Title bulunmalıdır. Version doğru olmalıdır. Description anlamlı olmalıdır. Contact aktif olmalıdır. Ownership metadata eksik kalmamalıdır.

API Owner Tanımlı mı?

Owner takım belirli olmalıdır. Catalog ile eşleşmelidir. Support kanalı aktif olmalıdır. Code owner bulunabilir. Sahipsiz API production'a çıkmamalıdır.

Tüm Endpoint'ler Dokümante mi?

Runtime routes ile spec karşılaştırılabilir. Hidden internal endpoint ayrıca değerlendirilmelidir. Public contract eksiksiz olmalıdır. Deprecated operation görünür kalmalıdır. Coverage metriği kullanılabilir.

operationId'ler Benzersiz mi?

Duplicate operationId olmamalıdır. Naming convention izlenmelidir. SDK output test edilmelidir. Linter kontrol etmelidir. Stable isimler korunmalıdır.

Tüm Parameters Açıklanmış mı?

Path parametre required olmalıdır. Query semantiği açıklanmalıdır. Header formatı bulunmalıdır. Defaults doğru olmalıdır. Example eklenmelidir.

Request Örnekleri Var mı?

En önemli create ve update operation'larda example bulunmalıdır. Schema ile uyumlu olmalıdır. PII içermemelidir. CI validate etmelidir. Minimum çalışan örnek tercih edilmelidir.

Response Örnekleri Var mı?

Success örneği bulunmalıdır. Error example eklenmelidir. Schema ile uyumlu olmalıdır. Null davranışı görülebilir. Sanitized data kullanılmalıdır.

Error Response'lar Var mı?

Sadece 2xx yeterli değildir. Validation hatası belgelenmelidir. Authentication hatası bulunmalıdır. Rate limit varsa 429 eklenmelidir. Common schema kullanılmalıdır.

Authentication Tanımlı mı?

Security scheme açık olmalıdır. Protected operation doğru requirement kullanmalıdır. Public endpoint istisnası kontrollü olmalıdır. Gerçek token bulunmamalıdır. OAuth URL'leri doğru ortamı göstermelidir.

Pagination Standarda Uygun mu?

Liste endpoint'leri ortak modeli kullanmalıdır. limit sınırı doğru olmalıdır. Cursor davranışı açıklanmalıdır. Response metadata tutarlı olmalıdır. Lint ile kontrol edilebilir.

Spectral Lint Geçiyor mu?

Ruleset error üretmemelidir. Warning gözden geçirilmelidir. Doğru version kullanılmalıdır. Exception kayıtlı olmalıdır. CI sonucu artifact olarak saklanabilir.

Breaking-Change Testi Geçiyor mu?

Base spec doğru seçilmelidir. Kırıcı fark olmamalıdır. Varsa approval bulunmalıdır. Migration planı hazırlanmalıdır. Version değişikliği yapılmalıdır.

Contract Testleri Geçiyor mu?

Runtime response spec'e uymalıdır. Status code doğru olmalıdır. Header contract karşılanmalıdır. Error scenario test edilmelidir. Drift bulunmamalıdır.

Gerçek Secret veya PII Var mı?

Secret scan çalıştırılmalıdır. Example data incelenmelidir. Screenshot kontrol edilmelidir. Gerçek token bulunmamalıdır. PII sentetik veriye dönüştürülmelidir.

Swagger UI Erişimi Güvenli mi?

Public ve internal sınır kontrol edilmelidir. Authentication uygulanabilir. Try It Out riski değerlendirilmelidir. Production write erişimi sınırlanabilir. VPN ihtiyacı belirlenmelidir.

Changelog Güncel mi?

Release değişiklikleri eklenmelidir. Breaking fark öne çıkarılmalıdır. Deprecation bilgisi bulunmalıdır. Migration linki çalışmalıdır. Version ile eşleşmelidir.

Kurumsal API Standardizasyon Kontrol Listesi

Kurumsal seviyede yalnız tek API'nin iyi olması yeterli değildir. Merkezi style guide, machine-readable ruleset ve shared component library birlikte çalışmalıdır. Standard error, pagination, versioning ve deprecation politikaları tüm ekipler tarafından erişilebilir olmalıdır. API catalog ve ownership bilgileri görünür olmalı, breaking change approval süreci açıkça tanımlanmalıdır. API Quality Score gibi ölçümler standardın gerçekten uygulanıp uygulanmadığını göstermelidir.

Merkezi API Style Guide Var mı?

Kurallar tek kaynakta bulunmalıdır. Her ekip erişebilmelidir. Örnekler eklenmelidir. Version history tutulmalıdır. RFC süreciyle güncellenmelidir.

Style Guide Machine-Readable Ruleset'e Dönüştürüldü mü?

Otomatikleştirilebilir kurallar kodlaştırılmalıdır. Spectral kullanılabilir. Ruleset test edilmelidir. Package olarak versionlanabilir. CI ve IDE aynı kaynağı kullanmalıdır.

Her Repository Aynı Ruleset'i Kullanıyor mu?

Farklı kopyalar drift yaratır. Merkezi dependency tercih edilmelidir. Version pinlenebilir. Upgrade automation yapılabilir. Compliance dashboard bunu kontrol edebilir.

Ortak Component Library Var mı?

Error ve pagination ortaklaştırılabilir. Security scheme paylaşılabilir. Versioning uygulanmalıdır. Domain model gereksiz bağlanmamalıdır. Dependency governance gerekir.

Standard Error Model Var mı?

Tüm servisler aynı temel error yapısını kullanmalıdır. Machine code bulunmalıdır. Message insan tarafından okunabilir olmalıdır. Correlation ID desteklenmelidir. Validation details standardize edilmelidir.

Standard Pagination Var mı?

Liste endpoint'leri aynı convention izlemelidir. limit ve cursor isimleri ortak olmalıdır. Metadata paylaşılmalıdır. Maximum limit tanımlanmalıdır. İstisnalar review edilmelidir.

Standard Versioning Var mı?

Major version stratejisi belirlenmelidir. URI veya header yaklaşımı seçilmelidir. API ve OpenAPI version ayrılmalıdır. Breaking change tetikleyicileri yazılmalıdır. Migration policy eklenmelidir.

Standard Deprecation Policy Var mı?

Minimum notice süresi belirlenmelidir. Sunset date zorunlu olabilir. Migration guide hazırlanmalıdır. Consumer notification yapılmalıdır. Kapatma approval süreci bulunmalıdır.

API Catalog Var mı?

Tüm API'ler discovery edilebilmelidir. Spec linki bulunmalıdır. Owner gösterilmelidir. Lifecycle state görünmelidir. Catalog otomatik güncellenmelidir.

Her API'nin Sahibi Var mı?

Owner zorunlu metadata olmalıdır. Support kanalı aktif olmalıdır. Repository sahipliği eşleşmelidir. Organizasyon değişikliği senkron olmalıdır. Sahipsiz API raporlanmalıdır.

Breaking Change Approval Süreci Var mı?

Diff otomatik çalışmalıdır. Kırıcı değişiklik merge'i engelleyebilir. API owner onay verebilir. Migration planı zorunlu olabilir. Exception audit kaydı tutulmalıdır.

API Quality Score Ölçülüyor mu?

Coverage metrikleri toplanmalıdır. Lint compliance izlenmelidir. Contract tests ölçülmelidir. Owner completeness görülebilir. Score ekip gelişimini desteklemek için kullanılmalıdır.

Sık Sorulan Sorular

Swagger ve OpenAPI konusunda en sık sorulan sorular genellikle terminology, version seçimi, production güvenliği ve standardizasyon etrafında toplanır. Aşağıdaki cevaplar yeni başlayan geliştiriciden kurumsal platform ekibine kadar farklı seviyelerde hızlı başvuru noktası sunar. Teknik karar verirken yalnız tek araca değil, tüm API lifecycle sürecine bakmak gerekir. Özellikle OpenAPI version seçimi tooling compatibility ile birlikte değerlendirilmelidir. Kurumsal API yönetiminde asıl hedef güncel, test edilebilir ve geriye uyumlu bir contract oluşturmaktır.

Swagger nedir?

Swagger bugün ağırlıklı olarak OpenAPI çevresindeki araç ekosistemiyle ilişkilidir. Swagger UI specification'ı görselleştirir. Swagger Editor yazımı kolaylaştırır. Tarihsel Swagger specification OpenAPI'nin önceki dönemidir. Güncel teknik belgelerde specification için OpenAPI ifadesi daha açıktır.

OpenAPI nedir?

OpenAPI HTTP API'lerini tanımlayan açık specification'dır. Endpoint ve schema modelini belirtir. Security tanımları içerir. YAML veya JSON ile yazılabilir. Tooling tarafından makine olarak işlenebilir.

Swagger ile OpenAPI arasındaki fark nedir?

OpenAPI specification'dır. Swagger araç isimlerinde kullanılan ekosistem markasıdır. Swagger UI OpenAPI dosyasını okuyabilir. Swagger Editor OpenAPI yazabilir. İki kavram bağlantılıdır fakat aynı değildir.

Swagger UI ne işe yarar?

Swagger UI specification'ı görsel reference haline getirir. Endpoint'leri gösterir. Schema modellerini listeler. Try It Out sağlayabilir. Developer guide'ın tamamının yerine geçmez.

Swagger Editor ne işe yarar?

Swagger Editor OpenAPI yazmayı kolaylaştırır. Syntax feedback verir. Preview gösterir. Design-first süreçte kullanılabilir. Kurumsal ruleset yine ayrıca uygulanmalıdır.

OpenAPI YAML mı JSON mu olmalıdır?

İki format da geçerlidir. İnsan tarafından düzenlenen spec'te YAML okunabilir olabilir. Generated çıktıda JSON pratiktir. Format API davranışını değiştirmez. Ekip standardı tutarlı olmalıdır.

Güncel OpenAPI sürümü hangisidir?

OpenAPI specification ailesinde 3.2.0 yayımlanmış güncel sürümler arasında yer alır. Ancak yeni projede version seçimi yalnız numaraya göre yapılmamalıdır. Swagger UI, generator, gateway ve linter desteği kontrol edilmelidir. 3.1 bazı araç zincirlerinde hâlâ daha geniş uyumluluk sunabilir. Kurumsal ekipler compatibility matrix hazırlamalıdır.

OpenAPI 3.0 ile 3.1 arasındaki fark nedir?

3.1 schema tarafında JSON Schema ile daha yakın uyum sunar. Null modelleme yaklaşımı değişir. Bazı yeni özellikler eklenir. Tooling davranışı farklı olabilir. Migration gerçek spec üzerinde test edilmelidir.

OpenAPI 3.2 kullanılmalı mı?

Yeni projede değerlendirilebilir. Güncel specification yeteneklerinden yararlanmak avantaj sağlar. Ancak tüm araç zincirinin desteği doğrulanmalıdır. Kritik generator desteklemiyorsa kontrollü geçiş planı gerekebilir. Karar ekip compatibility ihtiyacına göre verilmelidir.

Swagger UI production'da kullanılabilir mi?

Kullanılabilir fakat erişim politikası gerekir. Internal endpoint public spec'e çıkmamalıdır. Try It Out write operasyonlarında risk yaratabilir. Authentication veya VPN uygulanabilir. Staging deneme için daha güvenli olabilir.

API-first nedir?

API-first contract'ı geliştirme öncesinde merkeze alır. Consumer ve provider birlikte tasarım yapar. Mock server erken kullanılabilir. Breaking issue koddan önce bulunabilir. OpenAPI ortak sözleşme görevi görür.

Code-first ile design-first arasındaki fark nedir?

Code-first koddan specification üretir. Design-first specification'dan implementasyona gider. İki yaklaşımın farklı avantajları vardır. Her ikisinde drift kontrolü gereklidir. Proje bağlamına göre seçim yapılmalıdır.

OpenAPI dokümanı kodla nasıl senkron tutulur?

Golden source belirlenmelidir. Spec'ten kod veya koddan spec üretilebilir. CI diff kontrolü yapılmalıdır. Runtime contract tests çalışmalıdır. Drift bulunduğunda pipeline durdurulabilir.

Spectral nedir?

Spectral specification linting aracıdır. OpenAPI kurallarını kontrol edebilir. Custom ruleset destekler. IDE ve CI içinde çalıştırılabilir. API style guide policy as code haline getirilebilir.

API Style Guide nedir?

Style guide ortak API tasarım kurallarını tanımlar. Naming ve URI yapısını belirler. Error ve pagination standardını açıklar. Versioning politikasını içerir. Otomatik kontrol edilebilen kurallar ruleset'e dönüştürülebilir.

OpenAPI breaking change nasıl tespit edilir?

Eski ve yeni specification karşılaştırılır. Structural diff kullanılır. Required field ve endpoint değişikliği bulunur. Kırıcı fark raporlanır. CI merge'i gerektiğinde engelleyebilir.

Swagger ile SDK üretilebilir mi?

OpenAPI specification code generation aracı için input olabilir. TypeScript ve Python gibi diller desteklenebilir. operationId method isimlerini etkiler. Schema kalitesi generated modeli etkiler. SDK test ve versioning süreci ayrıca yönetilmelidir.

Swagger UI tek başına yeterli API dokümantasyonu sağlar mı?

Reference için güçlüdür. Tutorial ihtiyacını tek başına karşılamaz. Authentication guide ayrıca gerekir. Business workflow developer portal içinde anlatılabilir. Swagger UI ve portal birlikte daha iyi sonuç verir.

OpenAPI ile contract testing yapılabilir mi?

Evet, specification test sözleşmesi olarak kullanılabilir. Request validate edilebilir. Response schema kontrol edilebilir. Status code doğrulanabilir. CI drift'i otomatik yakalayabilir.

API dokümantasyonu nasıl standardize edilir?

Önce style guide hazırlanır. Canonical OpenAPI contract kullanılır. Reusable components oluşturulur. Spectral rules uygulanır. CI içinde diff ve contract testing eklenir.

API geliştirmek için en iyi programlama dili hangisidir?

Tek bir en iyi dil yoktur. Ekip deneyimi önemlidir. Operasyon gereksinimi değerlendirilmelidir. Framework ekosistemi seçimi etkiler. Sağlam API contract dil seçiminden daha uzun ömürlüdür.

API geliştiricisi olmak için ne öğrenilmeli?

HTTP ve REST temelleri öğrenilmelidir. Bir backend dili seçilmelidir. Authentication ve security çalışılmalıdır. OpenAPI ve testing öğrenilmelidir. Git ve CI/CD pratiği kazanılmalıdır.

Open source ve işbirliği API standardizasyonuna nasıl katkı sağlar?

Açık araçlar ortak öğrenmeyi kolaylaştırır. Style guide örnekleri incelenebilir. Ruleset ekipçe geliştirilebilir. Pull request review kültürü güçlenir. Ortak standart sürekli iyileştirilebilir.

API dokümantasyonunda Swagger nasıl kullanılır ve standart bir yapı nasıl oluşturulur?

Önce canonical bir OpenAPI specification hazırlanmalıdır. Swagger UI bu sözleşmeyi görsel reference olarak sunabilir. operationId, tags, errors, authentication ve examples için style guide oluşturulmalıdır. Spectral lint ve contract testing CI içinde çalıştırılmalıdır. Böylece Swagger ile API dokümantasyonu nasıl hazırlanır sorusunun cevabı yalnız UI kurulumuyla sınırlı kalmaz ve yaşayan bir API contract sürecine dönüşür.

Swagger ile OpenAPI Specification arasındaki fark nedir?

OpenAPI Specification API sözleşmesini tanımlayan standarttır. Swagger adı ise Swagger UI ve Swagger Editor gibi araçlarla ilişkilidir. Bir OpenAPI dosyasını farklı araçlar okuyabilir. Swagger UI bu dosyayı görselleştiren seçeneklerden biridir. Teknik iletişimde specification ve tooling ayrımını açık tutmak yanlış version kararlarını önler.

Swagger dokümantasyonunda endpoint, request, response, hata kodları ve authentication bilgileri nasıl standartlaştırılmalıdır?

Endpoint naming için ortak URI standardı kullanılmalıdır. Request ve response schemas reusable components üzerinden modellenmelidir. Hata cevapları tek machine-readable error formatına bağlanmalıdır. securitySchemes ve operation security gereksinimleri açık biçimde tanımlanmalıdır. Kurumsal API dokümantasyonunda endpoint schema authentication ve versioning standartları aynı style guide ve lint ruleset içinde yönetildiğinde sonuç çok daha sürdürülebilir olur.

Kurumsal projelerde Swagger dokümantasyonunun güncel kalması ve CI/CD süreçlerinde otomatik doğrulanması nasıl sağlanır?

OpenAPI specification Git repository içinde canonical source olarak tutulmalıdır. Pull request aşamasında syntax validation, Spectral lint ve breaking change detection çalıştırılmalıdır. Staging API contract tests ile gerçek response'lar specification'a göre doğrulanmalıdır. Başarılı merge sonrasında Swagger UI ve SDK aynı spec'ten otomatik üretilmelidir. Bu yaklaşım kurumsal Swagger OpenAPI dokümantasyon ve API standardizasyon hizmeti oluştururken temel otomasyon modelini sağlar.

Swagger ve API dokümantasyonu standardizasyonu konusunda yakınımda danışmanlık veya eğitim nerede bulabilirim?

Swagger OpenAPI ve API danışmanlığı yakınımda şeklinde arama yapıyorsanız yalnız teorik anlatım değil, gerçek proje ve birlikte üretim imkânı sunan teknik toplulukları değerlendirmek faydalıdır. Diyarbakır'da API tasarımı, backend geliştirme, test ve açık kaynak çalışmalarına ilgi duyuyorsanız Diyarbakır Yazılım Topluluğu ile bağlantı kurabilirsiniz. Topluluk projeleri üzerinden OpenAPI, testing ve CI/CD konularını uygulamalı biçimde ele almak mümkündür. Kurumsal API standardı oluşturmak isteyen ekipler de style guide, Spectral ruleset ve contract testing yaklaşımını birlikte değerlendirebilir. Erişim için https://www.diyarbakiryazilim.com.tr adresini kullanabilirsiniz.

Sonuç: Swagger'ı Dokümantasyon Aracından API Governance Sistemine Dönüştürmek

API Dokümantasyonunda Swagger Kullanımı ve Standardizasyon yalnız Swagger UI ekranı oluşturmak anlamına gelmemelidir. Asıl değer OpenAPI specification'ı ekiplerin üzerinde uzlaştığı, test ettiği ve versionladığı bir API contract haline getirmektir. Style guide, Spectral lint, breaking change detection ve contract testing aynı pipeline içinde çalıştığında dokümantasyon koddan kopmaz. SDK, mock server ve developer reference aynı canonical spec'ten üretildiğinde tekrar eden manuel bakım büyük ölçüde azalır. API standardizasyonunu gerçek projeler üzerinde geliştirmek ve topluluk çalışmalarına katılmak için https://www.diyarbakiryazilim.com.tr adresine ulaşabilirsiniz.

OpenAPI'yi Single Source of Truth Yapın

Canonical specification belirleyin. Git içinde versionlayın. Tüm çıktıların aynı dosyadan üretilmesini sağlayın. Manuel kopyaları azaltın. Contract ownership'i açıkça tanımlayın.

Swagger UI'yi OpenAPI Contract'ın Görsel Katmanı Olarak Kullanın

UI reference görevi görsün. Endpoint bilgisini elle tekrar yazmayın. Developer guide'ı ayrı tutun. Production erişimini güvenli yapılandırın. Gösterilen spec'in canonical olduğundan emin olun.

Kurumsal API Style Guide Oluşturun

Naming ve URI standardını yazın. Error modelini tanımlayın. Pagination ve versioning politikasını belirleyin. Security beklentisini ekleyin. Kuralları örneklerle destekleyin.

Kuralları Spectral ile Otomatik Uygulayın

Ruleset hazırlayın. IDE feedback sağlayın. CI lint çalıştırın. Kritik ihlalde build'i durdurun. Ruleset'i normal kod gibi versionlayın.

Breaking Change'leri CI/CD'de Engelleyin

Base ve yeni spec'i karşılaştırın. Kırıcı farkları raporlayın. Approval olmadan merge etmeyin. Versioning ve migration sürecini tetikleyin. Consumer'ları önceden bilgilendirin.

Contract Testleriyle Spec ve Gerçek API'nin Uyumunu Doğrulayın

Staging API'yi düzenli test edin. Response schema'yı doğrulayın. Status code ve header'ları kontrol edin. Drift bulunduğunda pipeline'ı durdurun. Dokümantasyonu test edilebilir varlık haline getirin.

Dokümantasyon, SDK ve Mock Server'ı Aynı Spec'ten Üretin

Tek kaynak bakım maliyetini düşürür. Swagger UI otomatik güncellenir. SDK aynı operationId'leri kullanır. Mock examples ile eşleşir. Consumer deneyimi daha tutarlı hale gelir.

API Ownership ve Lifecycle Bilgisini Standardize Edin

Her API'nin sahibi olsun. Support kanalı görünür olsun. Lifecycle state catalog'da tutulsun. Deprecation ve sunset tarihleri kaydedilsin. Organizasyon değişiklikleri otomatik yansıtılsın.

Swagger/OpenAPI'yi Tek Seferlik Doküman Değil Yaşayan Bir API Sözleşmesi Olarak Yönetin

Specification her code değişikliğiyle birlikte yaşamalıdır. Pull request review sürecinden geçmelidir. CI tarafından doğrulanmalıdır. Runtime contract tests ile gerçek sistemle karşılaştırılmalıdır. Bu yaklaşım Swagger ve OpenAPI yatırımını yalnız dokümantasyon çıktısından çıkarıp sürdürülebilir API governance modeline dönüştürür.