Haruskah REST API Mengimplementasikan Tautan Hipermedia HATEOAS?

Intinya

HATEOAS (Hypermedia as the Engine of Application State) secara teoritis elegan tetapi secara praktis rumit. Sebagian besar API melewatkan HATEOAS penuh dan menggunakan tautan hipermedia selektif untuk penomoran halaman, sumber daya terkait, dan tindakan. Modern PetstoreAPI mengimplementasikan tautan hipermedia praktis tanpa memaksa klien untuk sepenuhnya didorong oleh hipermedia.

Pendahuluan

Anda sedang membaca tentang desain REST API. Anda menjumpai HATEOAS (Hypermedia as the Engine of Application State). Penjelasannya mengatakan: “Klien harus menemukan semua tindakan melalui tautan hipermedia, bukan URL yang dikodekan secara manual.”

Anda berpikir: “Kedengarannya rumit. Apakah ada yang benar-benar melakukan ini?”

Jawabannya: tidak juga. HATEOAS adalah batasan REST yang paling sering dilewati. Roy Fielding (yang menciptakan REST) mengatakan itu penting. Sebagian besar desainer API mengatakan itu tidak praktis. Hasilnya: sebagian besar API “REST” tidak benar-benar RESTful menurut definisi Fielding.

Modern PetstoreAPI mengambil pendekatan pragmatis: gunakan tautan hipermedia di mana mereka menambah nilai (penomoran halaman, sumber daya terkait, tindakan) tetapi jangan memaksa klien untuk sepenuhnya didorong oleh hipermedia.

💡

Jika Anda sedang membangun atau menguji REST API, Apidog membantu Anda menguji tautan hipermedia, memvalidasi format tautan, dan memastikan API Anda menyediakan navigasi yang berguna. Anda dapat memverifikasi kebenaran tautan dan menguji alur kerja yang didorong oleh hipermedia.

tombol

Dalam panduan ini, Anda akan mempelajari apa itu HATEOAS, mengapa kontroversial, dan cara mengimplementasikan tautan hipermedia praktis menggunakan Modern PetstoreAPI sebagai referensi.

Apa Itu HATEOAS?

HATEOAS adalah batasan REST yang menyatakan bahwa klien harus menemukan kapabilitas API melalui tautan hipermedia, bukan dokumentasi.

Konsep

Alih-alih mengkodekan URL secara manual:

// 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`);

Klien mengikuti tautan dari respons:

// 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

Dengan HATEOAS:

1. Klien tidak mengkodekan URL secara manual

URL dapat berubah tanpa merusak klien. Server mengontrol struktur URL.

2. Klien menemukan kapabilitas

Jika tautan ada, tindakan tersedia. Jika tidak, itu tidak tersedia (atau tidak diizinkan untuk pengguna ini).

3. API mendokumentasikan diri sendiri

Klien menjelajahi API dengan mengikuti tautan, seperti menjelajahi situs web.

Contoh: Respons HATEOAS Penuh

{
  "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"
    }
  }
}

Klien tidak perlu mengetahui pola URL. Klien hanya mengikuti tautan.

Perdebatan HATEOAS

HATEOAS kontroversial karena teori dan praktik berbeda.

Argumen Mendukung HATEOAS

1. Kopling longgar

Klien tidak bergantung pada struktur URL. Server dapat mengubah URL tanpa merusak klien.

2. Dapat Ditemukan

Klien dapat menjelajahi API tanpa membaca dokumentasi.

3. Tindakan Berbasis Status

Tautan menunjukkan tindakan apa yang tersedia. Jika hewan peliharaan diadopsi, tautan “adopt” akan hilang.

4. REST Sejati

Roy Fielding mengatakan HATEOAS sangat penting untuk REST. Tanpa itu, Anda tidak melakukan REST.

Argumen Menentang HATEOAS

1. Kompleksitas

Klien membutuhkan logika penguraian hipermedia. Klien HTTP sederhana menjadi mesin keadaan yang kompleks.

2. Performa

Klien membuat beberapa permintaan untuk menemukan URL. Akses URL langsung lebih cepat.

3. Kesulitan Debugging

Mengikuti tautan membuat debugging lebih sulit. Anda tidak bisa hanya curl sebuah URL—Anda perlu mengikuti rantai tautan.

4. Perkakas yang Buruk

Sebagian besar klien HTTP, alat pengujian, dan generator dokumentasi mengasumsikan URL yang dikodekan secara manual.

5. Tidak Ada yang Melakukannya

GitHub, Stripe, Twilio, Twitter—API besar tidak menggunakan HATEOAS penuh. Jika mereka tidak membutuhkannya, apakah Anda?

Kenyataan

Sebagian besar API mengklaim sebagai “REST” tetapi melewati HATEOAS. Mereka sebenarnya adalah “API HTTP” atau “API yang mirip REST.” REST sejati (dengan HATEOAS) jarang ditemukan.

Tautan Hipermedia Praktis

Alih-alih HATEOAS penuh, gunakan tautan hipermedia di mana mereka menambah nilai.

1. Tautan Penomoran Halaman

Masalah: Klien perlu membuat URL penomoran halaman.

Solusi: Sediakan tautan berikutnya/sebelumnya.

{
  "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"
  }
}

Manfaat: Klien tidak membuat URL penomoran halaman. Mereka hanya mengikuti tautan.

2. Tautan Sumber Daya Terkait

Masalah: Klien perlu mengetahui pola URL untuk sumber daya terkait.

Solusi: Sediakan tautan ke sumber daya terkait.

{
  "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"
  }
}

Manfaat: Klien menemukan sumber daya terkait tanpa dokumentasi.

3. Tautan Tindakan

Masalah: Klien perlu mengetahui tindakan apa yang tersedia.

Solusi: Sediakan tautan untuk tindakan yang tersedia.

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "status": "AVAILABLE",
  "_links": {
    "adopt": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/adopt",
      "method": "POST"
    }
  }
}

Jika hewan peliharaan sudah diadopsi:

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "status": "ADOPTED",
  "_links": {
    // No "adopt" link - action not available
  }
}

Manfaat: Tautan menunjukkan tindakan yang tersedia berdasarkan status.

4. Penomoran Halaman Berbasis Kursor

Masalah: Klien perlu membuat URL kursor.

Solusi: Sediakan URL berikutnya/sebelumnya yang buram.

{
  "data": [...],
  "links": {
    "next": "https://petstoreapi.com/v1/pets?cursor=eyJpZCI6IjAxOWI0MTMyIn0"
  }
}

Manfaat: Klien tidak mengurai kursor. Mereka hanya mengikuti tautan.

Bagaimana Modern PetstoreAPI Menggunakan Hipermedia

Modern PetstoreAPI menggunakan tautan hipermedia selektif.

Tautan Penomoran Halaman

Semua titik akhir koleksi menyertakan tautan penomoran halaman:

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"
  }
}

Tautan Sumber Daya Terkait

Respons sumber daya menyertakan tautan ke sumber daya terkait:

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"
  }
}

Tidak Ada HATEOAS Penuh

Modern PetstoreAPI tidak mengharuskan klien untuk didorong oleh hipermedia. Klien dapat:

Opsi 1: Ikuti tautan (didorong oleh hipermedia)

const pet = await fetch(petUrl);
const ownerUrl = pet._links.owner.href;
const owner = await fetch(ownerUrl);

Opsi 2: Buat URL (tradisional)

const pet = await fetch(`https://petstoreapi.com/v1/pets/${petId}`);
const owner = await fetch(`https://petstoreapi.com/v1/users/${pet.ownerId}`);

Kedua pendekatan berfungsi. Tautan disediakan untuk kenyamanan, bukan penegakan.

Menguji API Hipermedia dengan Apidog

Apidog membantu Anda menguji tautan hipermedia dan memvalidasi kebenaran tautan.

Uji Kehadiran Tautan

Verifikasi bahwa respons menyertakan tautan yang diharapkan:

// 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');
});

Uji Validitas Tautan

Ikuti tautan dan verifikasi bahwa mereka berfungsi:

// 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);
  });
});

Uji Format Tautan

Verifikasi bahwa tautan mengikuti format yang diharapkan:

pm.test("Links are absolute URLs", () => {
  const links = pm.response.json().links;
  Object.values(links).forEach(link => {
    pm.expect(link).to.match(/^https:\/\//);
  });
});

Kapan Menggunakan HATEOAS

Gunakan tautan hipermedia saat mereka menambah nilai. Abaikan saat tidak.

Gunakan Tautan Hipermedia Untuk:

1. Penomoran halaman - Klien tidak boleh membuat URL penomoran halaman
2. Sumber daya terkait - Navigasi yang nyaman
3. Tindakan bergantung status - Tampilkan tindakan yang tersedia berdasarkan status sumber daya
4. Alur kerja kompleks - Pandu klien melalui proses multi-langkah

Lewati HATEOAS Untuk:

1. API CRUD sederhana - Klien dapat membuat URL dengan mudah
2. API Internal - Tim dapat mengkoordinasikan perubahan URL
3. API kritis performa - Tautan ekstra menambah ukuran respons
4. API Seluler - Bandwidth penting, tautan menambah overhead

Kesimpulan

HATEOAS secara teoritis elegan tetapi secara praktis rumit. Sebagian besar API melewatkan HATEOAS penuh dan menggunakan tautan hipermedia selektif di mana mereka menambah nilai.

Modern PetstoreAPI menunjukkan hipermedia praktis: tautan penomoran halaman, tautan sumber daya terkait, dan tautan tindakan—tanpa memaksa klien untuk sepenuhnya didorong oleh hipermedia.

Gunakan Apidog untuk menguji tautan hipermedia, memvalidasi kebenaran tautan, dan memastikan API Anda menyediakan navigasi yang berguna.

Poin-poin penting:

HATEOAS penuh jarang dan rumit
Tautan hipermedia selektif menambah nilai tanpa kerumitan
Tautan penomoran halaman adalah fitur hipermedia yang paling berguna
Jangan paksa klien untuk didorong oleh hipermedia
Uji tautan untuk memastikan mereka berfungsi dengan benar

Jelajahi dokumentasi Modern PetstoreAPI untuk melihat implementasi hipermedia praktis.

tombol

FAQ

Apakah HATEOAS diperlukan untuk REST API?

Menurut Roy Fielding (penemu REST), ya. Dalam praktiknya, tidak. Sebagian besar API “REST” melewatkan HATEOAS dan secara teknis adalah “API HTTP” atau “API yang mirip REST.”

Apa kepanjangan dari HATEOAS?

Hypermedia as the Engine of Application State. Ini berarti klien menemukan kapabilitas API melalui tautan hipermedia, bukan URL yang dikodekan secara manual.

Apakah API besar menggunakan HATEOAS?

Tidak. GitHub, Stripe, Twilio, dan sebagian besar API besar tidak menggunakan HATEOAS penuh. Mereka mungkin menyertakan beberapa tautan hipermedia (penomoran halaman, sumber daya terkait) tetapi tidak mengharuskan klien untuk didorong oleh hipermedia.

Apa perbedaan antara HATEOAS dan tautan hipermedia?

HATEOAS adalah batasan yang mengharuskan klien untuk sepenuhnya didorong oleh hipermedia. Tautan hipermedia hanyalah tautan dalam respons. Anda dapat menyertakan tautan tanpa memberlakukan HATEOAS.

Haruskah saya mengimplementasikan HATEOAS di API saya?

Mungkin tidak HATEOAS penuh. Gunakan tautan hipermedia selektif untuk penomoran halaman dan sumber daya terkait. Jangan paksa klien untuk didorong oleh hipermedia kecuali Anda punya alasan khusus.

Bagaimana cara menguji API HATEOAS?

Gunakan Apidog untuk memverifikasi kehadiran tautan, mengikuti tautan, dan memvalidasi kebenaran tautan. Uji bahwa tautan mengembalikan respons yang diharapkan.

Apa itu format HAL?

HAL (Hypertext Application Language) adalah format standar untuk tautan hipermedia. Ini menggunakan bidang _links dan _embedded. Modern PetstoreAPI menggunakan format tautan yang terinspirasi HAL.

Bisakah klien mengabaikan tautan hipermedia?

Ya. Jika API Anda menyediakan tautan tetapi tidak mengharuskan klien untuk menggunakannya, klien dapat membuat URL secara langsung. Ini adalah pendekatan pragmatis yang diambil sebagian besar API.