API geliştirme best practice, modern yazılım projelerinin temel taşlarından biridir. İyi tasarlanmış bir API, geliştirici deneyimini iyileştirir, entegrasyon maliyetlerini düşürür ve sistemin uzun vadeli sürdürülebilirliğini sağlar. Bu rehberde RESTful ve GraphQL API tasarımının en iyi uygulamalarını, güvenlik stratejilerini ve dokümantasyon yöntemlerini kapsamlı biçimde ele alıyoruz.
REST Mimarisi Prensipleri ve Temel Kavramlar
REST (Representational State Transfer), Roy Fielding tarafından 2000 yılında tanımlanan ve bugün web API'lerinin büyük çoğunluğunun temelini oluşturan mimari bir stildir. REST; stateless iletişim, uniform interface, client-server ayrımı, cacheability ve layered system gibi temel kısıtlamalar üzerine kuruludur. Bu prensiplere uymak, API'nizin ölçeklenebilir, güvenilir ve anlaşılması kolay olmasını sağlar.
- Kaynak Odaklı URL Tasarımı: URL'ler fiil değil isim içermelidir. /getUsers yerine /users, /deleteOrder yerine DELETE /orders/123 kullanın. Çoğul isimler tercih edin ve hiyerarşiyi URL yapısıyla yansıtın: /users/42/orders/7.
- HTTP Metodlarını Doğru Kullanın: GET (okuma), POST (oluşturma), PUT (tam güncelleme), PATCH (kısmi güncelleme), DELETE (silme) metodlarını semantik doğruluğuna göre uygulayın. Idempotent metodları (GET, PUT, DELETE) doğru şekilde implemente edin.
- HTTP Durum Kodları: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 500 Internal Server Error kodlarını doğru bağlamlarda kullanın. Hata mesajları anlamlı ve tutarlı olmalıdır.
- HATEOAS Prensibi: Hypermedia as the Engine of Application State, API yanıtlarına ilgili bağlantıları ekleyerek istemcinin API'yi keşfetmesini sağlar. Tam uygulama her projede zorunlu olmasa da bağlantı ekleme pratiği geliştirici deneyimini artırır.
API Versioning Stratejileri
API değişiklikleri kaçınılmazdır; ancak mevcut entegrasyonları bozmadan yeni özellikler sunabilmek için versioning stratejisi belirlemek gerekir. En yaygın yaklaşımlar arasında URL yolu versioning (/api/v1/users), header versioning (Accept: application/vnd.api+json;version=2) ve query parameter versioning (/api/users?version=1) bulunur. URL versioning, görünürlüğü ve test edilebilirliği nedeniyle en çok tercih edilen yöntemdir. Semantic versioning prensiplerine uyun ve eski sürümleri deprecation bildirimiyle birlikte en az 6-12 ay süre boyunca desteklemeye devam edin.
Authentication: OAuth2, JWT ve API Key
API güvenliğinin omurgasını kimlik doğrulama oluşturur. OAuth2, üçüncü taraf yetkilendirme için endüstri standardı olup Authorization Code, Client Credentials ve Implicit gibi farklı grant türleri sunar. JWT (JSON Web Token), stateless kimlik doğrulama için idealdir; payload'da kullanıcı bilgileri ve yetkiler taşınır. JWT'lerin kısa ömürlü (15-60 dakika) olması ve refresh token mekanizmasıyla desteklenmesi güvenliği artırır. API Key, makine-makine iletişimde tercih edilen basit bir yöntemdir; ancak header üzerinden iletilmeli ve düzenli döndürülmelidir. HTTPS olmadan hiçbir authentication yöntemi güvenli değildir.
Rate Limiting ve Throttling
Rate limiting, API'nizin kötüye kullanımını ve aşırı yüklenmeyi önler. Token bucket, leaky bucket ve fixed window algoritmaları yaygın implementasyonlardır. Kullanıcı başına, IP başına veya API key başına farklı limitler tanımlayabilirsiniz. Limit aşımında 429 Too Many Requests döndürün ve Retry-After header'ı ekleyin. Redis tabanlı rate limiting, dağıtık sistemlerde tutarlı sonuç verir. API planlamanızda farklı katmanlar (free, pro, enterprise) oluşturarak iş modelinizi de desteklemiş olursunuz.
GraphQL: Ne Zaman Tercih Edilmeli?
GraphQL, Facebook tarafından 2015 yılında açık kaynak olarak yayımlanan ve REST'e alternatif sunan bir sorgu dilidir. İstemcinin tam olarak ihtiyaç duyduğu veriyi talep etmesine olanak tanıyan GraphQL, over-fetching ve under-fetching sorunlarını ortadan kaldırır. Tek endpoint üzerinden tüm operasyonlar (query, mutation, subscription) gerçekleştirilir. Mobil uygulamalar, karmaşık veri ilişkileri ve sık değişen frontend gereksinimleri için GraphQL avantaj sağlar. Bununla birlikte, basit CRUD işlemleri ve cache yönetimi için REST daha pratiktir. N+1 sorgu problemi, DataLoader gibi araçlarla çözülmelidir. Apollo Server ve Hasura, popüler GraphQL implementasyonlarıdır.
API Dokümantasyonu: Swagger ve OpenAPI
İyi dokümantasyon, API'nin benimsenmesini doğrudan etkiler. OpenAPI Specification (eski adıyla Swagger), API'nizi makine okunabilir YAML veya JSON formatında tanımlamanızı sağlar. Swagger UI, bu tanımdan otomatik olarak interaktif dokümantasyon oluşturur. Code-first veya design-first yaklaşımlardan birini seçin; design-first, API tasarım hatalarını erken aşamada yakalamanızı sağlar. Postman Collection, alternatif bir dokümantasyon ve test aracıdır. API değişikliklerini versiyon kontrol sisteminizle senkronize tutun ve örnek istek/yanıtlar ekleyin.
- Caching Stratejisi: GET istekleri için HTTP cache header'ları (Cache-Control, ETag, Last-Modified) kullanın. Redis veya Memcached ile uygulama katmanında cache ekleyin. CDN caching, statik API yanıtları için bant genişliği tasarrufu sağlar. Cache invalidation stratejisini baştan planlayın.
- Error Handling: Tutarlı hata formatı belirleyin: error code, message, details ve timestamp içeren JSON yanıtları. Stack trace asla production'da dönmemeli, loglanmalıdır. Problem Details (RFC 7807) standardını benimseyin.
- Test Otomasyonu: Unit test, integration test ve contract test (Pact) katmanları oluşturun. Postman Newman veya REST Assured ile API testlerini CI/CD pipeline'ına entegre edin. Performans testi için k6 veya Apache JMeter kullanın.
Sık Sorulan Sorular
REST mi yoksa GraphQL mi seçmeliyim?
Basit CRUD operasyonları, public API'ler ve güçlü cache gereksinimi için REST tercih edin. Karmaşık veri ilişkileri, mobil öncelikli uygulamalar ve frontend ekibinin hızlı iterasyon yaptığı projelerde GraphQL avantajlıdır. İkisi birlikte de kullanılabilir; kritik performans gerektiren uç noktalar REST, esnek sorgulama gerektiren alanlar GraphQL ile tasarlanabilir.
JWT token süresi ne kadar olmalıdır?
Access token için 15-60 dakika ideal süredir. Kısa ömürlü token, çalınma durumunda maruz kalma penceresini daraltır. Refresh token ise 7-30 gün geçerli olabilir ve güvenli HTTP-only cookie'de saklanmalıdır. Hassas işlemler için step-up authentication (ek doğrulama adımı) uygulayabilirsiniz. Token refresh sürecini şeffaf biçimde yönetmek kullanıcı deneyimini bozmaz.
API rate limiting değerlerini nasıl belirlemeliyim?
Önce API kullanım analizinizi yapın; normal kullanıcı davranışını modelleyin. Tipik değerler: ücretsiz katman için dakikada 60 istek, ücretli katman için 1000 istek. Burst kapasitesine izin verin ancak sürekli yüksek trafiği kısıtlayın. Müşteri segmentlerine göre farklı limitler tanımlayın ve limit bilgisini X-RateLimit-Limit, X-RateLimit-Remaining header'larıyla istemciye iletin.
API dokümantasyonu ne sıklıkla güncellenmelidir?
API dokümantasyonu, kod değişiklikleriyle eş zamanlı güncellenmelidir. Code-first yaklaşımda, annotation'lardan otomatik dokümantasyon üretimi bu süreci kolaylaştırır. CI/CD pipeline'ınıza dokümantasyon validation adımı ekleyin; dokümantasyonu güncel tutmayan PR'ların merge edilmesini engelleyin. Changelog tutmak, API tüketicilerini değişiklikler hakkında proaktif biçimde bilgilendirir.
Sonuç
API geliştirme best practice uygulamak, kısa vadede ekstra çaba gerektirse de uzun vadede bakım maliyetlerini dramatik biçimde düşürür ve geliştirici deneyimini üst düzeye çıkarır. REST prensiplerini doğru uygulamak, doğru authentication yöntemini seçmek ve kapsamlı dokümantasyon oluşturmak başarılı bir API'nin temel unsurlarıdır. Toserof Tech. olarak yazılım altyapısı projeleriniz için iletişime geçin.