RESTful API Tasarım Rehberi: Richardson Maturity Model ve Best Practices

Richardson Maturity Model: RESTful Olgunlaşma Seviyeleri

Başarılı API tasarımı, Leonard Richardson'ın geliştirdiği Richardson Maturity Model'e dayanır. Bu model, bir API'nin ne kadar RESTful olduğunu ölçmek için 4 seviye (0-3) tanımlar. Bu seviyeleri anlamak, sistemlerinizi daha etkili şekilde tasarlamanıza yardımcı olur.

Level 0: The Swamp of POX

En temel seviyede, API'ler tek bir endpoint kullanır ve tüm istekler POST yöntemiyle gönderilir. İşlem türü istek gövdesinde belirtilir. Bu yaklaşım HTTP protokolünün standart metodlarını ve durum kodlarını görmezden gelir, bu da API'nin anlaşılmasını ve bakımını zorlaştırır.

Level 1: Resources

Bu seviyede, API'ler kaynak kavramını tanır. Farklı kaynaklar için ayrı endpoint'ler oluşturulur: /users, /products, /orders. Her endpoint belirli bir veri koleksiyonunu temsil eder. Ancak işlemler hala çoğunlukla POST yöntemiyle yapılır.

Level 2: HTTP Verbs

Level 2, HTTP metodlarının doğru kullanıldığı olgun tasarımı gösterir. GET veri okumak için, POST oluşturmak, PUT/PATCH güncellemek ve DELETE silmek için kullanılır. Uygun HTTP durum kodları (200, 201, 404, 500 vb.) döndürülür. Çoğu modern API bu seviyeyi hedefler çünkü pratik, anlaşılır ve bakımı kolaydır.

Level 3: HATEOAS

En RESTful seviyesi, HATEOAS (Hypermedia As The Engine Of Application State) ilkesini uygular. API yanıtları ilgili işlemlerin bağlantılarını içerir. İstemci, API'nın yapısını dinamik olarak keşfedebilir ve API değişse bile eski istemciler çalışmaya devam eder. Pek çok şirket bu seviyelinin karmaşıklığını gereksiz bulsa da, uzun vadede bakım maliyetlerini azaltır.

---

HTTP Metodları ve Status Kodları

Doğru HTTP metodlarının seçilmesi, API'nizin profesyonelliğini ve kullanılabilirliğini artırır.

HTTP Metodu	Amaç	İdempotent	Safe
GET	Veri okuma	Evet	Evet
POST	Yeni kaynak oluşturma	Hayır	Hayır
PUT	Tam kaynak güncelleme	Evet	Hayır
PATCH	Kısmi kaynak güncelleme	Hayır*	Hayır
DELETE	Kaynak silme	Evet	Hayır
HEAD	GET gibi ama gövde olmaz	Evet	Evet
OPTIONS	İzin verilen metodları sorgulama	Evet	Evet

*PATCH, dikkatlice tasarlanırsa idempotent olabilir.

Durum kodlarının doğru seçilmesi, istemcilerin yanıtı yorumlamasını kolaylaştırır. 200 başarılı GET isteklerini, 201 kaynak oluşturmayı, 204 içeriksiz başarılı yanıtları gösterir. Hata tarafında 400 geçersiz istekleri, 401 kimlik doğrulaması gerektiren durumları, 404 bulunamayan kaynakları, 422 semantik hataları ve 500 sunucu hatalarını belirtir.

Kod	Anlamı	Kullanım
200	OK	Başarılı GET, PUT, PATCH
201	Created	Başarılı POST (kaynak oluşturma)
204	No Content	Başarılı DELETE veya başarılı ancak yanıt boş
400	Bad Request	Geçersiz istek parametreleri
401	Unauthorized	Kimlik doğrulaması gerekli
403	Forbidden	Kimlik doğrulanmış ama yetkilendirme yok
404	Not Found	Kaynak bulunamadı
409	Conflict	Çakışan veri veya durum
422	Unprocessable Entity	Semantik hata
429	Too Many Requests	Rate limiting uyarısı
500	Internal Server Error	Sunucu hatası
503	Service Unavailable	Geçici hizmet kesintisi

---

Kaynak Adlandırma Kuralları

Tutarlı kaynak adlandırması, API'nizin kullanılabilirliğini önemli ölçüde artırır.

Best Practices

Endpoint'ler için çoğul formlar kullanın: /users değil /user, /products/123 değil /product/123. Küçük harfler ve kısa çizgiler tercih edin: /user-profiles en uygun formattır. Alt kaynaklar hiyerarşik olarak yapılandırılmalıdır: /users/123/orders/456 kullanıcı 123'ün sipariş 456'sını temsil eder.

Filtreleme ve arama işlemleri için sorgu parametreleri kullanın: /users?role=admin&status=active veya /users/search?q=ahmet. URL'de eylem adları yer almadığı zaman, API daha temiz ve anlaşılır olur.

API sürümü URL'de yer alabilir: /v1/users, /v2/users. Bu, gelecekteki değişiklikleri yönetmeyi kolaylaştırır.

---

Hata Yönetimi Standardı

Tutarlı hata yanıtları, API'nin güvenilirliğini ve profesyonelliğini gösterir. RFC 7807 standardı, hata mesajları için birleşik bir yapı tanımlar. Hata yanıtları tip, başlık, durum kodu, detay, zaman damgası ve istek izleme kimliği içermelidir. Bu bilgiler istemcinin hatayı anlaması ve sorunu teşhis etmesine yardımcı olur.

Validasyon hataları için ek alanlar içerebilirsiniz. Örneğin, e-posta formatı geçersiz veya yaş gereksinimleri karşılanmıyorsa, bu spesifik sorunlar hata yanıtında listelenir. Geliştirme ortamında stack trace bilgisi sağlanabilir, ancak üretim ortamında hassas teknik detaylar gizlenmelidir.

---

Pagination, Filtering ve Sorting

Büyük veri setleriyle çalışırken, pagination kritik önem taşır. Offset-Limit yaklaşımı en yaygındır ve basit veritabanı entegrasyonu sağlar: ?offset=20&limit=10 veya ?page=3&per_page=10. Keyset pagination, veri silinince atlanan satırlardan kaçındığı için daha stabil olabilir: ?after_id=150&limit=10.

Filtreleme, istemcilerin sonuçları daraltmasına izin verir: ?role=admin&status=active. Çok değerli filtreler virgülle ayrılır: ?role=admin,moderator. Sıralama, - ön eki ile azalan düzeni gösterir: ?sort=-created_at,name.

API yanıtları pagination bilgisini içermelidir: geçerli sayfa, limit, toplam kayıt sayısı, toplam sayfa sayısı ve daha fazla veri olup olmadığı. HATEOAS uyumlu API'ler next ve previous bağlantılarını da sağlar, böylece istemciler kolayca dolaşabilir.

---

İdempotency ve ETags

İdempotent işlemler kaç kez çalışırlarsa çalışsınlar aynı sonucu verir. PUT ve DELETE idempotent olmalı, POST ise çoğu zaman değildir. Yinelenen POST isteklerini önlemek için istemciler idempotency anahtarı gönderebilir. Sunucu, aynı anahtarla gelen isteği kontrol eder ve daha önceki yanıtı döndürür.

ETags, kaynağın geçerli sürümünü temsil eden hash değerleridir. İstemci, If-None-Match başlığında ETag gönderirse sunucu 304 Not Modified döndürebilir, bant genişliğini korur. PUT işlemlerinde, If-Match başlığı conflict'leri engeller: istemci eski sürümle güncellemeye çalışırsa, sunucu 412 Precondition Failed döndürür.

---

API Versiyonlama Stratejileri

Zamanlı API değişiklikleri zorunludur, ancak mevcut istemcileri etkilememelidir. URL path versiyonlama en yaygın ve önerilir: /api/v1/users ve /api/v2/users ayrı olarak çalışabilir. Bu yaklaşım açık, cache-friendly ve daha az kafa karıştırıcıdır.

Header versiyonlama, Accept başlığında versiyon bilgisi gerektirir: Accept: application/vnd.api+json;version=1. Query parameter versiyonlama mümkündür ancak daha az yaygındır.

Versiyonlama stratejiniz, kaç sürümü destekleyeceğinizi, eski sürümleri ne zaman kaldıracağınızı ve istemcileri geçişe nasıl yönlendireceğinizi açıkça belirtmelidir.

---

Testing ve Dokümantasyon

Profesyonel API'lar kapsamlı dokümantasyon gerektirir. OpenAPI ve Swagger standartları, makineler ve insanlar tarafından okunabilen API tanımlarını sağlar. Bu dokümantasyon, otomatik kod üretimi ve etkileşimli test ortamları (Swagger UI) oluşturmayı mümkün kılar.

Dokümantasyonunuz her endpoint'i, parametreleri, örnek istekleri ve yanıtları açıklaymalıdır. Hata durumları ve başarılı yanıtlar için açık örnekler sağlayın. Dokümantasyon, API değiştikçe güncellenmelidir aksi halde istemcileri yanılır.

Test edilmesi olmayan API'lar üretime hazır değildir. Unit testler ayrı komponenleri, integration testler bileşenlerin bir arada çalışmasını ve end-to-end testler tam iş akışlarını doğrulamalıdır.

---

Modern Framework'ler: NestJS ve Fastify

Node.js ekosisteminde, RESTful API geliştirmesi için iki güçlü framework bulunur. NestJS, TypeScript desteği, modüler mimari ve yerleşik IoC container sağlar. Yapı, büyük ekipler ve karmaşık uygulamalar için idealdir. Fastify, Node.js'deki en hızlı web framework'üdür. Minimal ve hafif yapısı, düşük latency gerektiren uygulamalara uygun. Her ikisi de profesyonel RESTful API geliştirmesi için iyi birer seçimdir.

---

Veritabanı ve Cache Mimarisi

Veritabanı seçimi, API'nin performansını ve ölçeklenebilirliğini belirler. PostgreSQL, relational veri için ACID uyumluluğu ve güçlü query optimization sağlar. Redis, in-memory cache katmanı olarak işlev görür, session yönetimi, rate limiting ve pub/sub messaging sağlayarak performansı önemli ölçüde artırır.

Tipik mimari şöyle olur: İstemciler API'ye istek gönderir, API Redis'te önbellek kontrol eder, bulamadığı veri PostgreSQL'den çeker ve Redis'e kaydeder. Bu katmanlı yaklaşım, database yükünü azaltır ve yanıt sürelerini kısaltır.

---

Best Practices Özeti

Başarılı REST API tasarımı, bu temel ilkelere uyumu gerektirir:

1. Richardson Maturity Level 2-3'ü hedefleyin; HTTP metodları ve HATEOAS'ı düzgün kullanın
2. Tutarlı ve sezgisel kaynak adlandırması uygulayın
3. Her durum için doğru HTTP status kodları döndürün
4. RFC 7807 standardını izleyen hata yanıtları sağlayın
5. Pagination, filtering ve sorting işlevselliğini dahil edin
6. İdempotency anahtarları ve ETags kullanarak veri tutarlılığını sağlayın
7. URL'de versiyon bilgisi gösterin
8. OpenAPI/Swagger dokümantasyonu sağlayın
9. Unit, integration ve end-to-end testler yazın
10. HTTPS, authentication ve authorization implementasyonu yapın

---

Sonuç

RESTful API tasarımı, modern yazılım mimarisinin temelidir. Richardson Maturity Model, HTTP metodları, hata yönetimi ve naming conventions gibi ilkeleri takip ederek, profesyonel, ölçeklenebilir ve bakımı kolay API'lar geliştirebilirsiniz.

Smart Maple, Ankara'da Node.js, Express, NestJS, Fastify ve PostgreSQL gibi teknolojileri kullanarak enterprise seviyesi API çözümleri sunmaktadır. Robust bir RESTful API'a ihtiyacınız varsa, smart-maple.com adresinden iletişime geçin ve nasıl yardımcı olabileceğimizi öğrenin.