Richardson Olgunluk Modeli (Richardson Maturity Model): API Tasarımında Doğru Yolu Bulmak

2. Model Kaç Seviyeden Oluşur?

Richardson Olgunluk Modeli toplam 4 seviyeden oluşur:

• Seviye 0: Tek endpoint, ne yapılacağı içerikte (body) yazılır
• Seviye 1: Farklı endpoint'ler var ama hep aynı yöntem kullanılıyor (genelde POST)
• Seviye 2: Endpoint’ler de HTTP methodları da doğru
• Seviye 3: Sistem sadece cevap vermez, yön de gösterir (linklerle)

Her seviye, bir öncekine göre daha düzenli ve anlaşılır bir yapı sunar. Hedef: en az Seviye 2.

3. Seviye 0 – Swamp of POX (Bataklık)

Bu seviye, API tasarımının en dağınık halidir. Tüm işlemler tek bir endpoint üzerinden yapılır (/api gibi).

Ne yapılacağı, body içinde action olarak yazılır. Bu yaklaşım REST'e uygun değildir.

POX, “Plain Old XML” demektir. Günümüzde JSON kullanılsa da mantık aynıdır: eski usul, karmaşık yapı.

❌ Yanlış Örnek:

POST /api
{
  "action": "getUser",
  "userId": 123
}

✅ Doğru Örnek:

GET /users/123

Yanlışta: Her şey tek kapıdan giriyor, içeride ne yapılacağı yazıyla anlatılıyor.
Doğruda: Endpoint belli, ne yapılacağı da HTTP methodundan anlaşılıyor.

4. Seviye 1 – Kaynakların Tanımlanması

Bu seviyede artık her işlem için farklı endpoint'ler vardır. Yani /users, /products gibi yollar kullanılır.

Ama hâlâ tüm işlemler tek methodla (genelde POST) yapılır. Yani kapılar ayrılmış ama hep aynı anahtarla açılıyor.

❌ Yanlış Örnek:

POST /users/delete
{
  "userId": 123
}

✅ Doğru Örnek (Seviye 2'ye geçiş):

DELETE /users/123

Yanlışta: Endpoint doğru ama method yanlış.
Doğruda: Hem endpoint hem method ne yapılacağını açıkça gösteriyor.

5. Seviye 2 – Gerçek Anlamda Düzen

Bu seviyede artık sadece endpoint’ler değil, HTTP methodları da doğru şekilde kullanılır.

Yani hangi işlemi yapıyorsan, ona uygun bir yöntem (GET, POST, PUT, DELETE) kullanırsın.

Bu sayede API hem daha düzenli, hem de daha anlaşılır hale gelir.

✅ Doğru Kullanım Örnekleri:

• GET /products/10 → Ürünü getir
• POST /products → Yeni ürün oluştur
• PUT /products/10 → Ürünü tamamen güncelle
• DELETE /products/10 → Ürünü sil

Neden bu seviye önemli?
Çünkü artık bir endpoint'e bakarak o işlemin ne olduğunu hemen anlayabiliriz.
Anlam karışıklığı yok, kurallar net.

6. Seviye 3 – HATEOAS (Link’li API Yanıtları)

Bu seviyede API sadece veri döndürmez, aynı zamanda yol gösterir.

API yanıtlarının içinde, bir sonraki adımda neler yapılabileceğini gösteren linkler yer alır.

✅ Örnek Yanıt:

{
  "id": 10,
  "name": "Kalem",
  "_links": {
    "self":   { "href": "/products/10" },
    "update": { "href": "/products/10", "method": "PUT" },
    "delete": { "href": "/products/10", "method": "DELETE" }
  }
}

Faydası nedir?
İstemci (uygulama), bu linkleri takip ederek ne yapabileceğini anlayabilir.
Böylece API, kendini tarif eden bir sistem haline gelir.

Hiyerarşik JSON ≠ HATEOAS

Bazı geliştiriciler, JSON içinde başka nesneler (örneğin bir kategorinin içindeki sayfalar) dönünce bunun HATEOAS olduğunu sanır.

Hayır, bu HATEOAS değildir.

Hiyerarşik JSON Nedir?

{
  "id": 1,
  "name": "Blog",
  "pages": [
    { "id": 101, "title": "Anasayfa" },
    { "id": 102, "title": "İletişim" }
  ]
}

Bu sadece veridir. Alt nesneleriyle birlikte gelir, ama yön göstermez.

HATEOAS Nedir?

HATEOAS, "Hypermedia As The Engine Of Application State" demektir.

Yani veriyle birlikte, o veriye ne yapılabileceğini de gösteren linkler içerir.

{
  "id": 1,
  "name": "Blog",
  "_links": {
    "self":   { "href": "/categories/1" },
    "edit":   { "href": "/categories/1", "method": "PUT" },
    "delete": { "href": "/categories/1", "method": "DELETE" }
  }
}

Peki HATEOAS Kullanmalı mıyız?

Hayır, %90 projede kullanılmaz.

• Fazladan karmaşıklık getirir
• Frontend zaten endpoint'leri bilir
• Swagger gibi dokümantasyonlar yeterlidir

✅ Gerçek Dünya İçin Doğru Seviye: Seviye 2

Seviye 2 şunları sağlar:

• Doğru HTTP methodları (GET, POST, PUT, DELETE)
• Kaynaklar ayrı endpoint'lerle tanımlı
• Anlaşılır, sade, sürdürülebilir yapı

Sonuç: GET /products/10 veya DELETE /users/5 gibi istekler yapıyorsan, Seviye 2'densin. Ve bu zaten yeterlidir.

7. Seviye Karşılaştırma Özeti

Aşağıdaki tablo, dört seviyeyi basitçe özetler:

Gerçekçi hedef: Seviye 2. Çoğu proje için fazlasıyla yeterlidir.

8. Sonuç: Kaçıncı Seviyedesin?

Kendi yazdığın API'ye bir bak:

• Her şey /api gibi tek bir endpoint üzerinden mi yapılıyor?
• Silme işlemi POST /users/delete şeklinde mi?
• Yoksa DELETE /users/5 gibi doğru methodlarla mı çalışıyor?
• Yanıtlarda _links alanı var mı?

Eğer 3. soruda “evet” diyorsan, Seviye 2’desin. Ve bu çok iyi!

Hedefin; API’yi anlaşılır, düzgün ve sürdürülebilir yapmaksa Seviye 2 seni fazlasıyla taşır.

Son söz: REST'in kitabı Seviye 3'e kadar uzansa da, gerçek hayat Seviye 2'de gayet iyi çalışır.