RestApi ve HATEOAS Kavramı

Bazı şeyler vardır, her yerde öyle kullanıldığını görürsünüz ve siz de farkında olmadan öyle kullanmaya başlarsınız. Bir gün alaylı olarak öğrendiğiniz bu şeyin adını duyar ve "ben hep öyle yapıyordum, onun bir adı mı varmış" dersiniz. İşte ben bugün o 'bazı şeylerden' birini yaşadım ve yaşadığım aydınlanmayı sizlerle de paylaşmak istedim. O şeyin adı "HATEOAS", dokümantasyonlarda veya spesifikasyonlarda böyle böyle yapın diye öğrendiğimiz şeyin aslında bir adı varmış. :)

💡 Özet (TL;DR):
HATEOAS Nedir?: REST mimarisinin en olgun seviyesi (Level 3) olup, sunucunun veriyle birlikte istemcinin yapabileceği sonraki işlemleri gösteren dinamik bağlantıları (hypermedia) dönmesidir.
Kilit Fayda: İstemcinin sunucu URL şemalarından tamamen bağımsızlaşmasıdır. İstemci, URL yollarını sabit kodlamak (hardcode) yerine ilişkileri (rel) takip eder.
Motto: Decouple clients from server URIs using dynamic hypermedia links.

Richardson Olgunluk Modeli (Richardson Maturity Model)

HATEOAS'ın REST mimarisindeki yerini anlamak için, REST uyumluluğunu 4 seviyeye ayıran Richardson Olgunluk Modeli'ne bakmak gerekir:

Level 0 (Swamp of POX): Tek bir URI ve tek bir HTTP metodu (genellikle POST) kullanılır. Örnek: SOAP tabanlı servisler.
Level 1 (Resources): Kaynaklara özel farklı URI'lar tanımlanır ancak HTTP metotları standartlara uygun kullanılmaz veya tekilleştirilmez.
Level 2 (HTTP Verbs): Çoklu URI yapısı ile birlikte standart HTTP metotları (GET, POST, PUT, DELETE) ve HTTP durum kodları (200, 201, 404, 500 vb.) doğru şekilde kullanılır.
Level 3 (Hypermedia Controls - HATEOAS): API, döneceği hypermedia bağlantılarıyla kendi kendini belgeler ve istemciye sonraki adımları dinamik olarak gösterir.

HATEOAS vs. Standart REST

Özellik	Standart REST (Level 2)	HATEOAS REST (Level 3)
URL Çözümleme	İstemci tarafında sabit kodlanır (`/accounts/{id}/withdraw`)	Yanıttan dinamik olarak okunur (`links.withdraw`)
Durum Kararları	İstemci tarafındaki iş kurallarıyla yönetilir (`balance > 0`)	Sunucudan gelen link varlığına göre belirlenir (link varsa buton gösterilir)
Sunucu Değişiklikleri	Sunucuda URL değişirse istemci kırılır	İstemci etkilenmez, sadece ilişki anahtarını (`rel`) takip eder
API Bağımlılığı	URL yapısına sıkı sıkıya bağlıdır (Tight coupling)	Gevşek bağlıdır, son derece esnektir (Loose coupling)

HATEOAS Örneği

REST API'mizden bir makalenin bilgilerini istedik. Gelen veri; "Makale Başlığı ve Makale İçeriği" olacaktır. Bununla birlikte "Yazar", "Yorumlar", "Kategoriler" vb. ilişkili kaynaklar olduğu ve bu kaynaklara ulaşılabilecek "URL"ler de gönderilecektir.

Standart bir REST (Level 2) çıktısı sadece veriyi döner:

{
    "id": 42,
    "title": "RestApi ve HATEOAS Kavramı",
    "content": "HATEOAS İngilizce..."
}

HATEOAS uyumlu bir API ise ilişkili kaynaklara nasıl ulaşılacağını da bağlantılarla birlikte sunar:

{
    "id": 42,
    "title": "RestApi ve HATEOAS Kavramı",
    "content": "HATEOAS İngilizce...",
    "_links": {
        "self": { "href": "/articles/42" },
        "author": { "href": "/users/15" },
        "comments": { "href": "/articles/42/comments" },
        "categories": { "href": "/categories/8" }
    }
}

İstemci tarafında yazarın veya yorumların URL şemasının nasıl kurulduğunu bilmemiz gerekmez. Doğrudan "comments" anahtarındaki adrese istek atmak yeterlidir.

Vikipedi'deki Banka Hesabı Örneği

Uygulama durumunun (Application State) HATEOAS ile nasıl yönetildiğini anlamak için klasik banka hesabı örneğine bakalım.

İstemci, bakiyesi artı değerde olan bir HESAP (ACCOUNT) kaynağı için istek gönderir:

GET /accounts/12345 HTTP/1.1
Host: bank.example.com
Accept: application/vnd.acme.account+json

Geri dönen temsili cevap şudur:

HTTP/1.1 200 OK
Content-Type: application/vnd.acme.account+json

{
    "account": {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": 100.00
        },
        "links": {
            "deposit": "/accounts/12345/deposit",
            "withdraw": "/accounts/12345/withdraw",
            "transfer": "/accounts/12345/transfer",
            "close": "/accounts/12345/close"
        }
    }
}

Görüldüğü gibi, yatırma (deposit), çekme (withdraw), transfer ve kapatma (close) bağlantıları istemciye sunulmuştur.

Peki, hesap bakiyesinin eksiye düştüğü bir sonraki durumu sorguladığımızda ne olur?

HTTP/1.1 200 OK
Content-Type: application/vnd.acme.account+json

{
    "account": {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": -25.00
        },
        "links": {
            "deposit": "/accounts/12345/deposit"
        }
    }
}

Bu durumda bağlantılar içinde para çekme, transfer ve kapatma yer almaz, sadece para yatırma bağlantısı sunulur. İstemci tarafında "eğer bakiye 0'dan büyükse para çekme butonunu göster, küçükse gizle" gibi bir iş mantığı kurmaya gerek kalmaz. Sadece gelen yanıtta withdraw linkinin olup olmadığına bakılarak arayüz dinamik olarak şekillendirilir.

HATEOAS Bize Ne Sağlıyor?

Bağlantı Bağımsızlığı (Decoupled URIs): Sunucu tarafındaki URL'ler değişse bile (/accounts yerine /api/v2/accounts gelse dahi), istemci ilişkisel anahtarları (örn: deposit) takip ettiği için istemci kodunda güncelleme yapmaya gerek kalmaz.
Kolaylaştırılmış İstemci Mantığı: Karmaşık iş kuralları ve durum kontrolleri tamamen sunucu tarafında kalır. İstemci sadece linklerin varlığını denetler.
Kendi Kendini Belgeleme (Discoverability): API'yi kullanan geliştiriciler, statik belgelere bağımlı kalmadan linkleri takip ederek tüm API fonksiyonlarını dinamik olarak keşfedebilirler.

Sıkça Sorulan Sorular (FAQ)

HATEOAS neden tüm genel API'lerde yaygın olarak kullanılmıyor?

Teoride mükemmel olsa da, HATEOAS her yanıtta büyük link nesneleri taşıdığı için payload boyutunu artırır. Ayrıca istemci tarafında statik URL çağırmak yerine dinamik link tarayıcıları yazmak gerektiğinden geliştiriciler tarafından alışılagelmiş yöntemlere kıyasla daha karmaşık bulunur.

HATEOAS uygulamak için hangi standart formatlar kullanılır?

Düz JSON yerine, hypermedia ilişkilerini standartlaştıran şu formatlar tercih edilir:

HAL (Hypertext Application Language): _links ve _embedded alanlarıyla en yaygın ve sade JSON uzantısıdır.
Siren: Eylemleri, sınıfları ve şemaları barındıran daha gelişmiş bir formattır.
JSON-LD: Veri bağlamlarını küresel olarak birbirine bağlayan yapıdır.

Referans

Wikipedia contributors. "HATEOAS." Wikipedia, The Free Encyclopedia. Wikipedia, The Free Encyclopedia, 18 Mar. 2020. Web. https://en.wikipedia.org/w/index.php?title=HATEOAS&oldid=946088168.

Bu Yazıda Yapılan Değişiklikler

20.06.2026: Yazı tamamen modernize edildi. Richardson Olgunluk Modeli açıklaması, HATEOAS vs Standart REST karşılaştırma tablosu ve FAQ bölümü eklendi.
11.05.2022: Yazı özeti düzenlendi.