API geliştiriyorsan, doğru yapıp yapmadığını merak edersin. İşte bu soruya cevap: Richardson Olgunluk Modeli.
Bu model, API'ni 0'dan 3'e kadar seviyelendirir. Her seviye bir öncekinin hatasını düzeltir.
Kafa karıştırmadan, en sade haliyle anlatıyorum. Hazırsan başlayalım.
Richardson Olgunluk Modeli toplam 4 seviyeden oluşur:
Her seviye, bir öncekine göre daha düzenli ve anlaşılır bir yapı sunar. Hedef: en az Seviye 2.
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ı.
POST /api
{
"action": "getUser",
"userId": 123
}
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.
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.
POST /users/delete
{
"userId": 123
}
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.
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.
GET /products/10
→ Ürünü getirPOST /products
→ Yeni ürün oluşturPUT /products/10
→ Ürünü tamamen güncelleDELETE /products/10
→ Ürünü silNeden bu seviye önemli?
Çünkü artık bir endpoint'e bakarak o işlemin ne olduğunu hemen anlayabiliriz.
Anlam karışıklığı yok, kurallar net.
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.
{
"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.
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.
{
"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, "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" }
}
}
Hayır, %90 projede kullanılmaz.
Seviye 2 şunları sağlar:
Sonuç: GET /products/10
veya DELETE /users/5
gibi istekler yapıyorsan, Seviye 2'densin. Ve bu zaten yeterlidir.
Aşağıdaki tablo, dört seviyeyi basitçe özetler:
Seviye | Ne Var? | Ne Yok? |
---|---|---|
0 | Tek endpoint, action body içinde | Kaynak ayrımı, method kullanımı yok |
1 | Farklı endpoint'ler var | HTTP method'ları yanlış (genelde hep POST) |
2 | Endpoint ve method doğru | Yön gösteren linkler yok |
3 | Veri + ne yapılabileceği bilgisi (HATEOAS) | Gerçek dünyada nadiren kullanılır |
Gerçekçi hedef: Seviye 2. Çoğu proje için fazlasıyla yeterlidir.
Kendi yazdığın API'ye bir bak:
/api
gibi tek bir endpoint üzerinden mi yapılıyor?POST /users/delete
şeklinde mi?DELETE /users/5
gibi doğru methodlarla mı çalışıyor?_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.