REST API'leri HATEOAS Hipermedya Bağlantılarını Uygulamalı mı?
Kısaca
HATEOAS (Uygulama Durumunun Motoru Olarak Hipermedya) teorik olarak zarif ancak pratik olarak karmaşıktır. Çoğu API, tam HATEOAS'ı atlar ve sayfalama, ilgili kaynaklar ve eylemler için seçici hipermedya bağlantıları kullanır. Modern PetstoreAPI, istemcileri tamamen hipermedya odaklı olmaya zorlamadan pratik hipermedya bağlantıları uygular.
Giriş
REST API tasarımı hakkında okuyorsunuz. HATEOAS (Uygulama Durumunun Motoru Olarak Hipermedya) ile karşılaşıyorsunuz. Açıklamada şöyle diyor: “İstemciler tüm eylemleri URL'leri sabitlemek yerine hipermedya bağlantıları aracılığıyla keşfetmelidir.”
Şunu düşünüyorsunuz: “Bu karmaşık geliyor. Gerçekten bunu yapan var mı?”
Cevap: pek değil. HATEOAS, en çok atlanan REST kısıtlamasıdır. Roy Fielding (REST'i icat eden kişi) bunun temel olduğunu söyler. Çoğu API tasarımcısı ise pratik olmadığını belirtir. Sonuç: çoğu “REST” API'si, Fielding'in tanımına göre gerçekten RESTful değildir.
Modern PetstoreAPI pragmatik bir yaklaşım benimser: hipermedya bağlantılarını değer kattıkları yerlerde (sayfalama, ilgili kaynaklar, eylemler) kullanır ancak istemcileri tamamen hipermedya odaklı olmaya zorlamaz.
Bu rehberde, HATEOAS'ın ne olduğunu, neden tartışmalı olduğunu ve Modern PetstoreAPI'yi referans alarak pratik hipermedya bağlantılarını nasıl uygulayacağınızı öğreneceksiniz.
HATEOAS Nedir?
HATEOAS, istemcilerin API yeteneklerini belgeler aracılığıyla değil, hipermedya bağlantıları aracılığıyla keşfetmesi gerektiğini söyleyen bir REST kısıtlamasıdır.
Konsept
URL'leri sabitlemek yerine:
// Client hardcodes URLs
const response = await fetch('https://petstoreapi.com/v1/pets/123');
const pet = await response.json();
// Client knows the URL structure
await fetch(`https://petstoreapi.com/v1/pets/${pet.id}/orders`);
İstemciler yanıtlardaki bağlantıları takip eder:
// Client starts at root
const root = await fetch('https://petstoreapi.com/v1');
const rootData = await root.json();
// Client follows link to pets
const petsUrl = rootData._links.pets.href;
const pets = await fetch(petsUrl);
const petsData = await pets.json();
// Client follows link to specific pet
const petUrl = petsData._links.self.href;
const pet = await fetch(petUrl);
const petData = await pet.json();
// Client follows link to orders
const ordersUrl = petData._links.orders.href;
const orders = await fetch(ordersUrl);
Teori
HATEOAS ile:
1. İstemciler URL'leri sabitlemez
URL'ler, istemcileri bozmadan değişebilir. Sunucu URL yapısını kontrol eder.
2. İstemciler yetenekleri keşfeder
Bir bağlantı varsa, eylem kullanılabilir demektir. Yoksa, kullanılamaz (veya bu kullanıcı için izinli değildir).
3. API'ler kendi kendini belgeler
İstemciler, bir web sitesinde gezinir gibi bağlantıları takip ederek API'yi keşfeder.
Örnek: Tam HATEOAS Yanıtı
{
"id": "019b4132-70aa-764f-b315-e2803d882a24",
"name": "Fluffy",
"species": "CAT",
"status": "AVAILABLE",
"_links": {
"self": {
"href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24"
},
"update": {
"href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
"method": "PUT"
},
"delete": {
"href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
"method": "DELETE"
},
"orders": {
"href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders"
},
"adopt": {
"href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/adopt",
"method": "POST"
}
}
}
İstemcinin URL kalıplarını bilmesine gerek yoktur. Bağlantıları takip eder.
HATEOAS Tartışması
HATEOAS tartışmalıdır çünkü teori ve pratik birbirinden farklıdır.
HATEOAS Lehine Argümanlar
1. Gevşek bağlantı
İstemciler URL yapısına bağlı değildir. Sunucu, istemcileri bozmadan URL'leri değiştirebilir.
2. Keşfedilebilirlik
İstemciler, belge okumadan API'yi keşfedebilir.
3. Durum odaklı eylemler
Bağlantılar, hangi eylemlerin mevcut olduğunu gösterir. Bir evcil hayvan sahiplenildiğinde, “sahiplen” bağlantısı kaybolur.
4. Gerçek REST
Roy Fielding, HATEOAS'ın REST için temel olduğunu söyler. Onsuz REST yapmıyorsunuz demektir.
HATEOAS Aleyhine Argümanlar
1. Karmaşıklık
İstemcilerin hipermedya ayrıştırma mantığına ihtiyacı vardır. Basit HTTP istemcileri karmaşık durum makineleri haline gelir.
2. Performans
İstemciler URL'leri keşfetmek için birden fazla istek yapar. Doğrudan URL erişimi daha hızlıdır.
3. Hata ayıklama zorluğu
Bağlantıları takip etmek, hata ayıklamayı zorlaştırır. Bir URL'yi doğrudan curl ile çağıramazsınız—bağlantı zincirini takip etmeniz gerekir.
4. Yetersiz araçlar
Çoğu HTTP istemcisi, test aracı ve belge oluşturucu sabit kodlanmış URL'leri varsayar.
5. Kimse yapmıyor
GitHub, Stripe, Twilio, Twitter—büyük API'ler tam HATEOAS kullanmaz. Eğer onların buna ihtiyacı yoksa, sizin var mı?
Gerçeklik
Çoğu API “REST” olduğunu iddia eder ancak HATEOAS'ı atlar. Bunlar aslında “HTTP API'leri” veya “REST benzeri API'ler”dir. Gerçek REST (HATEOAS ile) nadirdir.
Pratik Hipermedya Bağlantıları
Tam HATEOAS yerine, değer kattıkları yerlerde hipermedya bağlantıları kullanın.
1. Sayfalama Bağlantıları
Sorun: İstemcilerin sayfalama URL'lerini oluşturması gerekir.
Çözüm: Sonraki/önceki bağlantıları sağlayın.
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"totalPages": 10
},
"links": {
"self": "https://petstoreapi.com/v1/pets?page=2&limit=20",
"first": "https://petstoreapi.com/v1/pets?page=1&limit=20",
"prev": "https://petstoreapi.com/v1/pets?page=1&limit=20",
"next": "https://petstoreapi.com/v1/pets?page=3&limit=20",
"last": "https://petstoreapi.com/v1/pets?page=10&limit=20"
}
}
Fayda: İstemciler sayfalama URL'lerini oluşturmaz. Bağlantıları takip ederler.
2. İlgili Kaynak Bağlantıları
Sorun: İstemcilerin ilgili kaynaklar için URL kalıplarını bilmesi gerekir.
Çözüm: İlgili kaynaklara bağlantılar sağlayın.
{
"id": "019b4132-70aa-764f-b315-e2803d882a24",
"name": "Fluffy",
"_links": {
"self": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
"orders": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders",
"owner": "https://petstoreapi.com/v1/users/019b4127-54d5-76d9-b626-0d4c7bfce5b6"
}
}
Fayda: İstemciler, belge olmadan ilgili kaynakları keşfeder.
3. Eylem Bağlantıları
Sorun: İstemcilerin hangi eylemlerin mevcut olduğunu bilmesi gerekir.
Çözüm: Mevcut eylemler için bağlantılar sağlayın.
{
"id": "019b4132-70aa-764f-b315-e2803d882a24",
"status": "AVAILABLE",
"_links": {
"adopt": {
"href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/adopt",
"method": "POST"
}
}
}
Evcil hayvan zaten sahiplenildiyse:
{
"id": "019b4132-70aa-764f-b315-e2803d882a24",
"status": "ADOPTED",
"_links": {
// No "adopt" link - action not available
}
}
Fayda: Bağlantılar, duruma göre mevcut eylemleri gösterir.
4. İmleç Tabanlı Sayfalama
Sorun: İstemcilerin imleç URL'lerini oluşturması gerekir.
Çözüm: Opak sonraki/önceki URL'leri sağlayın.
{
"data": [...],
"links": {
"next": "https://petstoreapi.com/v1/pets?cursor=eyJpZCI6IjAxOWI0MTMyIn0"
}
}
Fayda: İstemciler imleçleri ayrıştırmaz. Bağlantıları takip ederler.
Modern PetstoreAPI Hipermedyayı Nasıl Kullanır?
Modern PetstoreAPI seçici hipermedya bağlantıları kullanır.
Sayfalama Bağlantıları
Tüm koleksiyon uç noktaları sayfalama bağlantıları içerir:
GET /v1/pets?limit=20
{
"data": [...],
"pagination": {
"limit": 20,
"hasMore": true
},
"links": {
"self": "https://petstoreapi.com/v1/pets?limit=20",
"next": "https://petstoreapi.com/v1/pets?cursor=eyJpZCI6IjAxOWI0MTMyIn0&limit=20"
}
}
İlgili Kaynak Bağlantıları
Kaynak yanıtları, ilgili kaynaklara bağlantılar içerir:
GET /v1/pets/019b4132-70aa-764f-b315-e2803d882a24
{
"id": "019b4132-70aa-764f-b315-e2803d882a24",
"name": "Fluffy",
"ownerId": "019b4127-54d5-76d9-b626-0d4c7bfce5b6",
"_links": {
"self": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
"owner": "https://petstoreapi.com/v1/users/019b4127-54d5-76d9-b626-0d4c7bfce5b6",
"orders": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders"
}
}
Tam HATEOAS Yok
Modern PetstoreAPI, istemcilerin hipermedya odaklı olmasını gerektirmez. İstemciler şunları yapabilir:
1. Seçenek 1: Bağlantıları takip et (hipermedya odaklı)
const pet = await fetch(petUrl);
const ownerUrl = pet._links.owner.href;
const owner = await fetch(ownerUrl);
2. Seçenek 2: URL'leri oluştur (geleneksel)
const pet = await fetch(`https://petstoreapi.com/v1/pets/${petId}`);
const owner = await fetch(`https://petstoreapi.com/v1/users/${pet.ownerId}`);
Her iki yaklaşım da çalışır. Bağlantılar, zorlama amaçlı değil, kolaylık sağlamak için sunulmuştur.
Hipermedya API'lerini Apidog ile Test Etme
Apidog, hipermedya bağlantılarını test etmenize ve bağlantı doğruluğunu doğrulamanıza yardımcı olur.
Bağlantı Varlığını Test Etme
Yanıtların beklenen bağlantıları içerdiğini doğrulayın:
// Apidog test script
pm.test("Response includes pagination links", () => {
const links = pm.response.json().links;
pm.expect(links).to.have.property('self');
pm.expect(links).to.have.property('next');
});
Bağlantı Geçerliliğini Test Etme
Bağlantıları takip edin ve çalıştıklarını doğrulayın:
// Apidog test script
const nextUrl = pm.response.json().links.next;
pm.sendRequest(nextUrl, (err, response) => {
pm.test("Next link returns 200", () => {
pm.expect(response.code).to.equal(200);
});
});
Bağlantı Formatını Test Etme
Bağlantıların beklenen formatı takip ettiğini doğrulayın:
pm.test("Links are absolute URLs", () => {
const links = pm.response.json().links;
Object.values(links).forEach(link => {
pm.expect(link).to.match(/^https:\/\//);
});
});
HATEOAS Ne Zaman Kullanılmalı?
Değer kattıklarında hipermedya bağlantılarını kullanın. Katmadıklarında atlayın.
Hipermedya Bağlantılarını Şunlar İçin Kullanın:
1. Sayfalama - İstemciler sayfalama URL'lerini oluşturmamalıdır
2. İlgili kaynaklar - Kolay gezinme
3. Duruma bağlı eylemler - Kaynak durumuna göre mevcut eylemleri gösterin
4. Karmaşık iş akışları - İstemcileri çok adımlı süreçler boyunca yönlendirin
HATEOAS'ı Şunlar İçin Atlayın:
1. Basit CRUD API'leri - İstemciler URL'leri kolayca oluşturabilir
2. Dahili API'ler - Ekipler URL değişikliklerini koordine edebilir
3. Performans açısından kritik API'ler - Ek bağlantılar yanıt boyutunu artırır
4. Mobil API'ler - Bant genişliği önemlidir, bağlantılar ek yük getirir
Sonuç
HATEOAS teorik olarak zarif ancak pratik olarak karmaşıktır. Çoğu API, tam HATEOAS'ı atlar ve değer kattıkları yerlerde seçici hipermedya bağlantıları kullanır.
Modern PetstoreAPI, pratik hipermedyayı gösterir: sayfalama bağlantıları, ilgili kaynak bağlantıları ve eylem bağlantıları—istemcileri tamamen hipermedya odaklı olmaya zorlamadan.
Hipermedya bağlantılarını test etmek, bağlantı doğruluğunu doğrulamak ve API'nizin kullanışlı gezinme sağlamasından emin olmak için Apidog'u kullanın.
Temel çıkarımlar:
- Tam HATEOAS nadirdir ve karmaşıktır
- Seçici hipermedya bağlantıları, karmaşıklık yaratmadan değer katar
- Sayfalama bağlantıları, en kullanışlı hipermedya özelliğidir
- İstemcileri hipermedya odaklı olmaya zorlamayın
- Bağlantıların doğru çalıştığından emin olmak için test edin
Pratik hipermedya uygulamasını görmek için Modern PetstoreAPI belgelerini keşfedin.
Sıkça Sorulan Sorular
REST API'leri için HATEOAS gerekli midir?
Roy Fielding'e (REST'in mucidi) göre evet. Pratikte hayır. Çoğu "REST" API'si HATEOAS'ı atlar ve teknik olarak "HTTP API'leri" veya "REST benzeri API'ler"dir.
HATEOAS ne anlama geliyor?
Uygulama Durumunun Motoru Olarak Hipermedya (Hypermedia as the Engine of Application State). Bu, istemcilerin API yeteneklerini sabit kodlanmış URL'ler yerine hipermedya bağlantıları aracılığıyla keşfettiği anlamına gelir.
Büyük API'ler HATEOAS kullanır mı?
Hayır. GitHub, Stripe, Twilio ve çoğu büyük API, tam HATEOAS kullanmaz. Bazı hipermedya bağlantıları (sayfalama, ilgili kaynaklar) içerebilirler ancak istemcilerin hipermedya odaklı olmasını gerektirmezler.
HATEOAS ile hipermedya bağlantıları arasındaki fark nedir?
HATEOAS, istemcilerin tamamen hipermedya odaklı olmasını gerektiren bir kısıtlamadır. Hipermedya bağlantıları ise yanıtlardaki sadece bağlantılardır. HATEOAS'ı zorunlu kılmadan bağlantılar ekleyebilirsiniz.
API'imde HATEOAS uygulamalı mıyım?
Muhtemelen tam HATEOAS'ı değil. Sayfalama ve ilgili kaynaklar için seçici hipermedya bağlantıları kullanın. Belirli bir nedeniniz yoksa istemcileri hipermedya odaklı olmaya zorlamayın.
HATEOAS API'lerini nasıl test ederim?
Bağlantı varlığını doğrulamak, bağlantıları takip etmek ve bağlantı doğruluğunu onaylamak için Apidog'u kullanın. Bağlantıların beklenen yanıtları döndürdüğünü test edin.
HAL formatı nedir?
HAL (Hypertext Application Language), hipermedya bağlantıları için standart bir formattır. `_links` ve `_embedded` alanlarını kullanır. Modern PetstoreAPI, HAL'den ilham alan bir bağlantı formatı kullanır.
İstemciler hipermedya bağlantılarını görmezden gelebilir mi?
Evet. API'niz bağlantılar sağlıyor ancak istemcilerin bunları kullanmasını zorunlu kılmıyorsa, istemciler URL'leri doğrudan oluşturabilir. Bu, çoğu API'nin benimsediği pragmatik yaklaşımdır.