API Tasarımı & REST Mimarisi 37 okunma

Richardson Olgunluk Modeli ve HATEOAS

Richardson Olgunluk Modeli (RMM), bir web servisinin REST ilkelerine ne kadar uygun olduğunu değerlendiren 4 seviyeli bir çerçevedir. HATEOAS (Hypermedia as the Engine of Application State), bu modelin en üst seviyesi olan Seviye 3'ün temelini oluşturur. Bu yazıda, Richardson Olgunluk Modeli'nin 4 seviyesi, HATEOAS prensibi, avantajları, zorlukları ve .NET'te uygulama stratejileri ele alınmaktadır.

Richardson Olgunluk Modeli ve HATEOAS

Richardson Olgunluk Modeli ve HATEOAS: Gerçek REST'in Peşinde

Leonard Richardson tarafından geliştirilen ve Martin Fowler tarafından popülerleştirilen Richardson Olgunluk Modeli (Richardson Maturity Model - RMM), bir API'nin REST prensiplerine ne kadar uygun olduğunu değerlendirmek için kullanılan 4 seviyeli bir çerçevedir. Model, URI tasarımı, HTTP metodlarının kullanımı ve hipermedya bağlantılarının (HATEOAS) uygulanması olmak üzere üç ana unsura odaklanır.

1. Richardson Olgunluk Modeli: 4 Seviye

A. Seviye 0: The Swamp of POX (POX Bataklığı)

  • Özellikler: Tek bir URI, tek bir HTTP metodu (genellikle POST) kullanılır. HTTP sadece bir taşıma protokolü olarak görülür.

  • Örnek: Tüm işlemler için POST /api/service kullanılır ve hangi işlemin yapılacağı istek gövdesinde (body) belirtilir.

  • Değerlendirme: REST'in en ilkel halidir. SOAP veya XML-RPC gibi eski tarz servisler bu seviyededir.

B. Seviye 1: Resources (Kaynaklar)

  • Özellikler: Birden fazla URI kullanılarak kaynaklar (resources) tanımlanır. Ancak hala tek bir HTTP metodu (POST) kullanılır.

  • Örnek: POST /api/users/123, POST /api/orders/456.

  • Değerlendirme: Kaynak kavramı tanıtılmıştır, ancak HTTP metotları henüz doğru kullanılmamaktadır.

C. Seviye 2: HTTP Verbs (HTTP Fiilleri)

  • Özellikler: HTTP metotları (GET, POST, PUT, DELETE) doğru anlamlarıyla kullanılır. Statü kodları (200, 404, 500) doğru şekilde döndürülür.

  • Örnek: GET /api/users/123, POST /api/users, PUT /api/users/123, DELETE /api/users/123.

  • Değerlendirme: Günümüzdeki çoğu REST API bu seviyededir. API'ler artık "RESTful" olarak anılmaya başlar.

D. Seviye 3: Hypermedia Controls (Hipermedya Kontrolleri) - HATEOAS

  • Özellikler: Yanıtlara, istemcinin bir sonraki adımda ne yapabileceğini gösteren hipermedya bağlantıları (link'ler) eklenir.

  • Örnek:

json

{
  "id": 5,
  "name": "Ahmet Yılmaz",
  "links": [
    { "rel": "self", "href": "/api/users/5" },
    { "rel": "update", "href": "/api/users/5", "method": "PUT" },
    { "rel": "delete", "href": "/api/users/5", "method": "DELETE" },
    { "rel": "orders", "href": "/api/users/5/orders" }
  ]
}

  • Değerlendirme: Roy Fielding'in tanımladığı "gerçek REST" anlayışına en yakın seviyedir. API, istemciye dokümantasyon okumadan hangi işlemleri yapabileceğini söyler.

2. HATEOAS (Hypermedia as the Engine of Application State)

HATEOAS, REST mimarisinin temel kısıtlamalarından biridir ve "Uygulama Durumunun Motoru Olarak Hipermedya" anlamına gelir.

Temel Fikir:

  • İstemci, API ile etkileşimini, sunucunun döndürdüğü hipermedya bağlantıları (link'ler, formlar) aracılığıyla yürütmelidir.

  • İstemci, URI'leri önceden bilmek veya sabit kodlamak zorunda değildir. Sunucu, mevcut duruma göre hangi eylemlerin mümkün olduğunu söyler.

  • Bu, bir web sitesinde gezinmeye benzer: Bir web sayfası, tıklanacak bağlantıları (link'leri) içerir.

HATEOAS'ın Sağladığı Avantajlar:

  • Keşfedilebilirlik (Discoverability): İstemciler, API yeteneklerini çalışma zamanında keşfedebilir.

  • Esneklik ve Dayanıklılık: Sunucu, URI şemasını değiştirdiğinde, istemciler link'leri dinamik olarak takip ettiği için değişiklikten etkilenmez.

  • Kendi Kendini Belgeleme (Self-descriptive): API yanıtları, mevcut kaynak ve eylemleri anlatan meta veriler içerir.

3. Neden Çoğu API Seviye 3'e Ulaşamıyor?

HATEOAS teorik olarak zarif olsa da, pratikte birçok API bu seviyeye ulaşmaz.

  • Karmaşıklık: HATEOAS uygulamak, API tasarımına ve geliştirmeye önemli bir karmaşıklık ekler.

  • İstemci Beklentileri: Çoğu istemci geliştiricisi, API'yi dokümantasyon (OpenAPI/Swagger) okuyarak veya SDK kullanarak tüketmeyi tercih eder; dinamik link takibi yaygın değildir.

  • Pratik Fayda: Çoğu senaryoda, Seviye 2 (HTTP Verbs) zaten yeterlidir. HATEOAS'ın sağladığı esneklik, getirdiği ek maliyete değmeyebilir.

  • Hipermedya Formatları: JSON, doğal olarak bir hipermedya formatı değildir. HAL (Hypertext Application Language), JSON-LD, SIREN gibi özel formatlar kullanmak gerekir.

4. .NET'te HATEOAS Uygulama Stratejileri

.NET Core/ASP.NET Core'da HATEOAS uygulamak için çeşitli yaklaşımlar mevcuttur:

A. Manuel Link Ekleme
En temel yöntem, her kaynak yanıtına manuel olarak link'ler eklemektir.

csharp

public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public List<LinkDto> Links { get; set; }
}

public class LinkDto
{
    public string Rel { get; set; }  // self, update, delete, vs.
    public string Href { get; set; }
    public string Method { get; set; } // GET, POST, PUT, DELETE
}

// Controller'da link'leri manuel oluşturma
[HttpGet("{id}")]
public IActionResult GetUser(int id)
{
    var user = _context.Users.Find(id);
    var dto = new UserDto
    {
        Id = user.Id,
        Name = user.Name,
        Links = new List<LinkDto>
        {
            new LinkDto { Rel = "self", Href = Url.Action(nameof(GetUser), new { id = user.Id }), Method = "GET" },
            new LinkDto { Rel = "update", Href = Url.Action(nameof(UpdateUser), new { id = user.Id }), Method = "PUT" },
            new LinkDto { Rel = "delete", Href = Url.Action(nameof(DeleteUser), new { id = user.Id }), Method = "DELETE" },
            new LinkDto { Rel = "orders", Href = Url.Action(nameof(GetUserOrders), new { id = user.Id }), Method = "GET" }
        }
    };
    return Ok(dto);
}

B. RestWithASPNET.HATEOAS (NuGet Paketi)
Bu paket, HATEOAS desteğini kolayca eklemek için attribute tabanlı bir yaklaşım sunar.

csharp

// 1. Paketi yükle: RestWithASPNET.HATEOAS
// 2. View Model'de ISupportsHyperMedia implemente et
public class BookVO : ISupportsHyperMedia
{
    public int Id { get; set; }
    public string Title { get; set; }
    public List<HyperMediaLink> Links { get; set; } = new List<HyperMediaLink>();
}

// 3. Controller metoduna [TypeFilter] ekle
[TypeFilter(typeof(HyperMediaFilter))]
public IActionResult Get(int id) { ... }

C. AspNetCore.Hateoas (NuGet Paketi)
ASP.NET Core MVC uygulamaları için JSON tabanlı HATEOAS desteği sunar.

D. FastEndpoints ile HATEOAS
FastEndpoints, modern ve hafif bir API framework'üdür ve HATEOAS link'lerini kolayca eklemenize olanak tanır.

5. HATEOAS'ı Ne Zaman Kullanmalısınız?

HATEOAS, her proje için gerekli değildir. Kullanmayı düşünmeniz gereken durumlar:

  • Büyük ve Karmaşık API'ler: Çok sayıda kaynak ve ilişki içeren, uzun ömürlü API'ler.

  • Genel / Harici API'ler: Farklı istemciler (web, mobil, 3. parti) tarafından tüketilen API'ler.

  • Hipermedya Odaklı Uygulamalar: İstemci deneyiminin dinamik olarak yönlendirilmesi gereken uygulamalar.

Basit projeler veya dahili mikroservis iletişimi için Seviye 2 (HTTP Verbs) genellikle yeterlidir.

Sonuç:

Richardson Olgunluk Modeli, bir API'nin REST ilkelerine uyumunu değerlendirmek için faydalı bir referans çerçevesidir. Seviye 3, HATEOAS ile gerçek REST'e en yakın noktadır. Ancak pratikte, çoğu API Seviye 2'de kalmakta ve HATEOAS'ı yalnızca sayfalama (pagination) gibi belirli durumlar için seçici olarak kullanmaktadır. Projenizin ihtiyaçlarına göre doğru dengeyi kurmak, başarılı bir API tasarımının anahtarıdır.

Tüm yazılar