REST API Tasarımında Kurumsal Sistemler İçin 12 Kritik Kural

REST API tasarımında amaç yalnız çalışan endpoint üretmek değil, yıllar boyunca farklı istemcilerin güvenilir biçimde kullanabileceği tutarlı bir sözleşme oluşturmaktır.

İsimlendirme, hata formatı veya pagination gibi küçük görünen kararlar API büyüdükçe ciddi entegrasyon maliyeti yaratabilir.

1. Resource Odaklı URL Tasarlayın

URL yapısı işlem isimleri yerine kaynakları temsil etmelidir. /orders veya /customers gibi yapılar API sözleşmesini daha anlaşılır hale getirir.

2. HTTP Methodlarını Doğru Kullanın

• GET: okuma
• POST: oluşturma
• PUT: tam güncelleme
• PATCH: kısmi güncelleme
• DELETE: silme

3. Status Code Tutarlılığı Sağlayın

200, 201, 400, 401, 403, 404, 409 ve 429 gibi kodlar istemcinin problemi doğru sınıflandırmasını kolaylaştırır.

4. Standart Hata Response’u Üretin

Hata response’unda kod, kullanıcıya gösterilebilir mesaj, teknik detail ve correlation ID gibi alanlar standardize edilebilir.

5. Pagination Kullanın

Binlerce kaydı tek response içinde döndürmek performans ve bellek problemi yaratabilir. Offset veya cursor pagination tercih edilebilir.

6. Filtering ve Sorting Standardı Belirleyin

Tarih, durum ve ID filtreleri her endpoint’te farklı isimlerle kullanılmamalıdır.

7. API Versioning Planlayın

Breaking change gerektiğinde mevcut istemcileri bozmamak için versioning stratejisi bulunmalıdır.

8. Validation Açık Olmalı

Geçersiz tarih, eksik zorunlu alan veya desteklenmeyen enum değeri açık hata mesajıyla dönmelidir.

9. Idempotency Gereken İşlemleri Belirleyin

Ödeme veya sipariş gibi tekrar gönderilmesi yan etki yaratabilecek POST işlemlerinde idempotency kullanılabilir.

10. Rate Limit Tanımlayın

API hem kötüye kullanımı hem de yanlış istemci davranışını sınırlamak için kapasiteye uygun rate limit uygulamalıdır.

11. Correlation ID Kullanın

Dağıtık sistemlerde tek işlemin farklı servislerdeki loglarını eşleştirmek için request veya correlation ID önemli avantaj sağlar.

12. API Sözleşmesini Dokümante Edin

OpenAPI spesifikasyonu endpoint, schema ve authentication bilgisini merkezi hale getirir ve SDK veya test üretiminde kullanılabilir.

Production Ortamında Entegrasyon Kontrol Listesi

REST API Tasarımında Kurumsal Sistemler İçin 12 Kritik Kural konusu production ortamına taşınırken 1. Resource Odaklı URL Tasarlayın, 2. HTTP Methodlarını Doğru Kullanın ve 3. Status Code Tutarlılığı Sağlayın yalnız geliştirme aşamasının değil işletim modelinin de parçası olmalıdır. Her entegrasyon için kaynak sistem, hedef sistem, data owner, authentication yöntemi, veri mapping tablosu ve hata sorumlusu açıkça tanımlanmalıdır. Bir endpoint teknik olarak çalışsa bile yanlış ürün, müşteri veya sipariş kaydını güncelliyorsa entegrasyon başarılı kabul edilmemelidir.

Üretim ortamında timeout, rate limit, geçici network kesintisi, duplicate request ve beklenmeyen response gibi senaryolar normal çalışma koşullarının parçası kabul edilmelidir. Retry yalnız geçici hatalara uygulanmalı, tekrar çalıştırılması finansal veya operasyonel yan etki yaratabilecek işlemlerde idempotency kullanılmalıdır. Uzun süren işler queue’ya taşındığında kullanıcı request’i dış servis performansına doğrudan bağımlı olmaktan çıkar; başarısız işler ise kontrollü biçimde yeniden işlenebilir.

Monitoring katmanında yalnız HTTP status code değil business sonucu da izlenmelidir. Örneğin API 200 response üretirken hiçbir sipariş ERP’ye işlenmemiş olabilir. Bu nedenle request count, error rate, P95 latency, retry sayısı, queue backlog ve son başarılı senkronizasyon zamanı gibi teknik metrikler; aktarılan sipariş, stok veya müşteri sayısı gibi iş metrikleriyle birlikte dashboard’a taşınmalıdır. Correlation ID ve structured logging kullanılması incident sırasında tek işlemin farklı servislerdeki izini takip etmeyi kolaylaştırır.

• Authentication ve secret yönetimi
• Veri mapping ve schema validation
• Timeout ve retry politikası
• Idempotency ve duplicate kontrolü
• Rate limit yönetimi
• Structured log ve correlation ID
• Business reconciliation
• Alert ve dashboard

API Sözleşmesi, Failure Mode ve Veri Tutarlılığı

REST API Tasarımında Kurumsal Sistemler İçin 12 Kritik Kural konusu production ortamında uygulanırken yalnız başarılı request-response akışı tasarlanmamalıdır. Özellikle 1. Resource Odaklı URL Tasarlayın, 2. HTTP Methodlarını Doğru Kullanın ve 3. Status Code Tutarlılığı Sağlayın için açık bir API sözleşmesi oluşturulmalıdır. Bu sözleşmede zorunlu alanlar, veri tipleri, enum değerleri, authentication yöntemi, timeout sınırı, hata kodları ve breaking change yaklaşımı tanımlanmalıdır. İstemci sistemin hangi response karşısında retry yapacağı, hangi durumda işlemi durduracağı ve hangi hatanın insan müdahalesine taşınacağı önceden belirlenirse entegrasyon davranışı daha öngörülebilir hale gelir.

Failure-mode tasarımında dış servisin tamamen erişilemez olması dışında yavaş response, kısmi veri, duplicate event, yanlış sıra ile gelen event, rate limit ve geçici authentication problemi de hesaba katılmalıdır. Retry uygulanacak işlemlerde exponential backoff ve uygun olduğunda jitter kullanılabilir. Sipariş, ödeme, stok veya müşteri kaydı gibi yan etkili işlemlerde idempotency veya benzersiz business key bulunması aynı isteğin tekrar işlenmesi sonucunda duplicate kayıt oluşma riskini azaltır.

Veri tutarlılığı açısından API response’unun başarılı olması tek başına yeterli değildir. Kaynak ve hedef sistem arasında periyodik reconciliation yapılması; kayıt sayısı, toplam tutar, son senkronizasyon zamanı veya business ID üzerinden uyuşmazlık kontrolü gerçekleştirilmesi gerekir. Structured log, correlation ID ve merkezi error tracking kullanıldığında bir işlemin hangi serviste başarısız olduğu daha hızlı bulunabilir. Bu kontroller entegrasyonu çalışan bir bağlantıdan çıkarıp denetlenebilir ve sürdürülebilir bir operasyon bileşenine dönüştürür.

• Request ve response schema doğrulaması
• Timeout ve retry matrisi
• Idempotency veya benzersiz business key
• Rate limit ve kapasite yönetimi
• Correlation ID ve structured logging
• Kaynak-hedef reconciliation kontrolü
• Breaking change ve versioning politikası

Sıkça Sorulan Sorular

REST API için JSON zorunlu mudur?

Hayır, ancak modern web API’lerinde en yaygın veri formatlarından biridir.

API versioning nasıl yapılır?

URL, header veya başka stratejiler kullanılabilir; önemli olan tutarlılık ve breaking change yönetimidir.

Her POST işlemi idempotent olmalı mı?

Zorunlu değildir fakat duplicate işlemin ciddi sonuç yaratacağı endpointlerde çok değerlidir.

OpenAPI nedir?

HTTP API sözleşmesini makine tarafından okunabilir biçimde tanımlayan spesifikasyondur.

İlgili İçerikler

• API-First Geliştirme: Backend’i Ayrıştırmak, Uygulamayı Çoklu Kanal Yapmak
• SEO + İçerik Yapısı için Headless CMS + GraphQL + Schema Best Practices
• Gerçek Zamanlı Web: WebSockets, Server-Sent Events ve Stream API