# API sözleşmesini tek doğruluk kaynağı hâline getirmek

> API sözleşmesini tek doğruluk kaynağı hâline getirip istemcileri, tipleri ve doğrulamaları elle kopyalamak yerine otomatik türetmek, iyi tanımlanmış bir API içeren her projede uyguladığım bir yöntem.

- Source canonique : [https://allaux.fr/tr/expertises/generation-de-code-depuis-openapi](https://allaux.fr/tr/expertises/generation-de-code-depuis-openapi)
- Langue : TR
- Dernière mise à jour : 2026-09-30

## Tipik ihtiyaç

Birden fazla tüketicinin — bir ön yüz, bir mobil uygulama, dış bir iş ortağı — kullandığı bir API'nin bulunduğu projelerde, veri alışverişi sözleşmesinin tarifi çoğu zaman birkaç yere kopyalanır: arka uç koduna, ön yüz koduna, ayrı bir dokümantasyona. Bu kopyalar zaman içinde neredeyse kaçınılmaz biçimde birbirinden ayrışır; arka uçta adı değiştirilen bir alan ön yüzde aynı anda güncellenmez, dokümantasyon kimsenin fark etmediği bir anda yanlış hâle gelir.

## Bu tür ihtiyaçlarda nasıl çalışıyorum

OpenAPI spesifikasyonu; bir API'nin uç noktalarını, parametrelerini, istek ve yanıt biçimlerini araçlar tarafından okunabilen yapılandırılmış bir formatta ayrıntılı olarak tanımlar. Bunu iş bittikten sonra yalnızca dokümantasyon amacıyla yazmak yerine, projenin doğruluk kaynağı olarak ele alıyorum: arka uç kodu bu spesifikasyondan üretilebilir veya ona göre doğrulanabilir; daha da önemlisi istemci kodu (tipler, çağrı fonksiyonları, doğrulamalar) her tüketici için elle kopyalanmadan otomatik üretilir.

Bu yaklaşım bir hata sınıfını canlı ortamda çalışma anından derleme ya da kod üretme anına taşır: spesifikasyonda adı değişen bir alan, haftalar sonra bir kullanıcı tarafından keşfedilen bir hata yerine, istemci kodu üretimini anında ve yeri belli açık bir hatayla durdurur. İlk kurulum, her API değişikliğinde spesifikasyonun güncellenmesi disiplinini gerektirir; bu da teknik bir zorluktan çok bir alışkanlık değişimidir.

## Fiyatlandırmayı etkileyen faktörler

- **Mevcut API mi, tasarlanacak API mi** — Hâlihazırda çalışan bir API'yi belgelemek, API oluşturulurken spesifikasyonu baştan tasarlamaktan farklı bir yeniden kurgulama çalışması ister.
- **API'yi kullanan tüketici sayısı** — Otomatik üretimin faydası, sözleşmeyle senkron tutulması gereken farklı istemci sayısı arttıkça büyür.
- **Veri tiplerinin karmaşıklığı** — İç içe geçmiş ya da çok sayıda doğrulama durumu içeren veri yapıları, yazması ve bakımı daha zahmetli, çok daha ayrıntılı bir spesifikasyon gerektirir.
- **Geliştirme zincirine entegrasyon** — Ara sıra elle üretim yapmak yerine her spesifikasyon değişikliğinde üretimi otomatikleştirmek, projenin araç setinde ek bir ilk kurulum çalışması gerektirir.

## Başlamadan önce sorulacak sorular

> Bu API'yi bugün ve ileride kaç farklı tüketici kullanacak? Resmileştirilecek gayriresmî bir dokümantasyon var mı, yoksa her şey sıfırdan mı tasarlanacak? Spesifikasyonu uzun vadede güncel tutmaktan kim sorumlu olacak?

## FAQ

### Bu yaklaşım hâlihazırda canlıda olan bir API için de geçerli mi?

Evet, mevcut bir API sonradan OpenAPI spesifikasyonu biçiminde belgelenebilir; ardından bu spesifikasyondan kod üretmeye kademeli olarak geçilebilir.

### Bu yöntemi benimsemek için dil veya framework değiştirmek gerekir mi?

Hayır, yaygın dillerin ve framework'lerin çoğu için kod üretim araçları mevcut; mevcut teknoloji yığınını sorgulamaya gerek kalmadan geçiş yapılabilir.

### Spesifikasyon güncel tutulmazsa ne olur?

Fayda giderek kaybolur; bu yüzden kod üretimini olağan geliştirme zincirine dâhil etmek önemlidir, böylece güncelleme kolayca unutulan bir görev değil doğal bir adım hâline gelir.