REST API Tasarım İlkeleri: Temiz ve Ölçeklenebilir API Geliştirme

Modern web uygulamalarının temelinde API'ler yatar ve doğru REST API tasarım ilkelerini uygulamak, bakımı kolay, ölçeklenebilir ve güvenli bir backend oluşturmanın anahtarıdır. Kötü tasarlanmış bir API, frontend ekibinin verimliliğini düşürür, entegrasyon süreçlerini uzatır ve güvenlik açıklarına davetiye çıkarır. Bu rehberde endpoint isimlendirmesinden hata yönetimine, versiyonlamadan güvenlik katmanlarına kadar REST API tasarımının temel ilkelerini pratik örneklerle ele alıyoruz.

REST API Nedir ve Neden Önemlidir?

REST (Representational State Transfer), Roy Fielding tarafından 2000 yılında tanımlanan bir mimari stildir. HTTP protokolü üzerinde çalışır ve istemci-sunucu arasında durumsuz (stateless) iletişim sağlar. Günümüzde mobil uygulamalar, SPA'lar ve mikroservis mimarileri REST API'lere bağımlıdır.

REST'in 6 Temel Kısıtı

Client-Server ayrımı, Statelessness, Cacheability, Uniform Interface, Layered System ve Code on Demand (opsiyonel) kısıtları REST mimarisinin temelini oluşturur. Bu kısıtlara uymak API'nizin ölçeklenebilirliğini ve bakım kolaylığını doğrudan artırır.

Endpoint Tasarımı ve İsimlendirme Kuralları

İyi bir endpoint yapısı, API'nin kendi kendini belgelemesini sağlar. Kaynak odaklı (resource-oriented) isimlendirme kullanın ve fiil yerine isim tercih edin.

Yanlış ❌	Doğru ✅	HTTP Metodu
GET /getUsers	GET /users	GET
POST /createUser	POST /users	POST
PUT /updateUser/5	PUT /users/5	PUT
DELETE /removeUser/5	DELETE /users/5	DELETE
GET /getUserOrders/5	GET /users/5/orders	GET

💡 İpucu: Endpoint'lerde çoğul isim kullanın (/users, /orders, /products). Tekil isim (/user) tutarsızlık yaratır ve koleksiyon ile tekil kaynak arasındaki farkı belirsizleştirir.

Hata Yönetimi ve HTTP Durum Kodları

Tutarlı hata yanıtları API tüketicilerinin hayatını kolaylaştırır. Her hata yanıtında HTTP durum kodu, hata mesajı ve detay bilgisi bulunmalıdır. Node.js production rehberimizde hata yönetimi middleware örneklerini inceleyebilirsiniz.

⚠️ Önemli: Hata mesajlarında hassas bilgi (veritabanı sorgusu, stack trace, sunucu yolu) döndürmeyin. Production ortamında genel hata mesajları kullanın ve detayları sunucu loglarına yazın.

API Versiyonlama Stratejileri

API'niz büyüdükçe breaking change'ler kaçınılmaz olur. Versiyonlama, mevcut istemcileri bozmadan yeni özellikler eklemenizi sağlar. En yaygın üç yaklaşım URL path versiyonlama (/v1/users), header versiyonlama (Accept: application/vnd.api+json;version=1) ve query parameter versiyonlama (?version=1) şeklindedir.

Pagination ve Filtreleme

Büyük veri setleri döndüren endpoint'lerde pagination zorunludur. Cursor-based pagination (offset'e göre daha performanslı) veya offset-based pagination kullanabilirsiniz. Filtreleme için query parameter'lar tercih edin: GET /products?category=electronics&min_price=100&sort=-created_at.

API Güvenlik Katmanları

API güvenliği kimlik doğrulama, yetkilendirme, rate limiting ve veri doğrulama katmanlarından oluşur. JWT (JSON Web Token) veya OAuth 2.0 ile kimlik doğrulama yapın. Docker geliştirme ortamı rehberimizde güvenli API geliştirme ortamı kurulumunu bulabilirsiniz. Ayrıca OWASP API Security Top 10 listesini mutlaka inceleyin.

Rate Limiting ve Throttling

API'nizi kötüye kullanıma karşı korumak için rate limiting uygulayın. Yanıt header'larında kalan istek sayısını (X-RateLimit-Remaining) ve sıfırlanma zamanını (X-RateLimit-Reset) bildirin. RFC 6585 standardına uygun 429 Too Many Requests yanıtı döndürün.

API Dokümantasyonu

İyi bir API, iyi bir dokümantasyon olmadan eksiktir. OpenAPI (Swagger) spesifikasyonu kullanarak API'nizi tanımlayın. Swagger UI veya Redoc ile interaktif dokümantasyon sunun. Her endpoint için istek/yanıt örnekleri, hata kodları ve kimlik doğrulama gereksinimleri belirtin. CI/CD pipeline rehberimizde dokümantasyon otomasyonunu da inceleyebilirsiniz.

Sıkça Sorulan Sorular

REST API ile GraphQL arasındaki fark nedir?

REST sabit endpoint'ler üzerinden kaynak odaklı çalışırken, GraphQL tek endpoint üzerinden istemcinin istediği veriyi sorgulamasına izin verir. Basit CRUD işlemleri için REST, karmaşık ve iç içe veri gereksinimleri için GraphQL tercih edilir.

API versiyonlama ne zaman gerekli olur?

Mevcut istemcileri bozacak değişiklikler (breaking changes) yapmanız gerektiğinde versiyonlama zorunludur. Alan kaldırma, yanıt yapısı değiştirme veya kimlik doğrulama mekanizması değişikliği gibi durumlarda yeni versiyon oluşturun.

JWT token süresi ne kadar olmalıdır?

Access token için 15-30 dakika, refresh token için 7-30 gün yaygın sürelerdir. Kısa access token süresi güvenliği artırır; refresh token ile kullanıcı deneyimini bozmadan yeni token alınır.

Sonuç

Temiz ve ölçeklenebilir bir REST API tasarımı; kaynak odaklı endpoint isimlendirmesi, tutarlı hata yönetimi, doğru versiyonlama stratejisi ve güçlü güvenlik katmanlarıyla mümkündür. Bu ilkeleri baştan uygulayarak hem geliştirici deneyimini hem de API'nizin uzun vadeli sürdürülebilirliğini garanti altına alırsınız.

API'leriniz İçin Güçlü Sunucu Altyapısı

Hosted Cloud bulut sunucuları ile REST API'lerinizi yüksek performanslı ve güvenli bir ortamda çalıştırın.

Bulut Sunucu Planlarını İncele →