Sebagian besar API RESTful sebenarnya tidak benar-benar RESTful

(florian-kraemer.net)

24 poin oleh GN⁺ 2025-07-10 | 1 komentar | Bagikan ke WhatsApp

Dalam makalah asli REST karya Roy Fielding, penggunaan metode HTTP atau API yang berpusat pada CRUD tidak ditetapkan secara eksplisit, dan REST pada dasarnya menekankan perancangan sistem berbasis hipermedia (HATEOAS)
Banyak hal yang disebut orang sebagai API RESTful tidak mengimplementasikan batasan penting REST (terutama penggunaan hipermedia)
Resource tidak terbatas pada struktur data atau entitas sederhana, tetapi mencakup semua konsep yang dapat diidentifikasi dengan URI
Menurut 6 aturan Fielding, navigasi yang berpusat pada hipermedia, independensi protokol, dan penekanan pada media type adalah inti utamanya
Dalam praktiknya, karena kemudahan alat dokumentasi seperti OpenAPI , kebanyakan API cenderung dirancang lebih dekat ke gaya RPC daripada benar-benar RESTful

Mengapa sebagian besar API RESTful tidak benar-benar RESTful

Makalah utama (2000) karya Roy Fielding menyajikan REST (Representational State Transfer) sebagai gaya ideal untuk perancangan perangkat lunak berbasis jaringan, dan menjelaskannya sebagai prinsip yang menopang keberhasilan web
Makalah tersebut tidak mewajibkan penggunaan metode HTTP atau desain yang berpusat pada CRUD, dan menekankan bahwa jika ingin berorientasi pada REST, inti utamanya adalah transisi status berbasis hipermedia (HATEOAS), antarmuka universal, dan interaksi yang berpusat pada resource

Hipermedia (HATEOAS) dan salah paham tentang REST

Fielding secara jelas menunjukkan bahwa API tanpa hipermedia bukanlah RESTful
- "Jika mesin tidak digerakkan oleh hypertext, maka itu bukan RESTful"
HATEOAS adalah pendekatan di mana klien menjelajahi tindakan secara dinamis dengan mengikuti link yang tertanam di dalam respons server
Hanya menggunakan antarmuka HTTP/CRUD semata berbeda dari esensi REST

Salah paham umum tentang REST

REST dipahami sebagai CRUD (padahal sebenarnya konsepnya jauh lebih luas)
Kesalahpahaman bahwa resource adalah entitas (struktur data di server)
Klaim bahwa API RESTful tidak boleh memakai kata kerja (verb)
Hal-hal ini hanyalah keputusan desain dan tidak berkaitan langsung dengan esensi REST

Makna sebenarnya dari pendekatan berbasis hipermedia (HATEOAS)

Tujuan HATEOAS adalah meminimalkan coupling antara klien dan server
Saat struktur URI di server berubah, pendekatan ini mengurangi beban redeploy klien sehingga skalabilitas dan kemampuan evolusi meningkat

Klien menjelajahi tindakan dengan mengikuti hyperlink dalam respons tanpa dokumen atau pengetahuan awal

{  
  "orderId": 123,  
  "_links": {  
    "self": { "href": "/orders/123" },  
    "cancel": { "href": "/orders/123/cancel", "method": "POST" }  
  }  
}

Seperti di atas, agar lebih mendekati RESTful yang sesungguhnya, respons harus menyertakan tindakan (link)

Apa yang dimaksud resource dalam REST?

Resource adalah segala sesuatu yang dapat diidentifikasi dengan URI
- Termasuk dokumen, gambar, objek fisik, layanan, konsep abstrak, dan lain-lain
Di server, yang benar-benar ada bukanlah "resource" secara fisik, melainkan hanya struktur pemetaan abstrak yang dapat diakses melalui URI
Bahkan dalam RFC 3986, cakupan resource tidak dibatasi
- Bisa mencakup dokumen elektronik, gambar, sumber informasi, layanan, bahkan orang, badan hukum, dan buku

6 aturan API RESTful yang didefinisikan oleh Fielding

1. Jangan bergantung pada satu protokol saja
- Identifikasi berbasis URI harus bisa dimanfaatkan di semua protokol
2. Jangan mengubah standar protokol (misalnya HTTP) secara sewenang-wenang
- Kekurangan dalam standar boleh dilengkapi, tetapi menambah atau mengubah aturan secara arbitrer tidak diperbolehkan
3. Fokus pada definisi media type (format), bukan struktur URI
- Fokus pada format data dan definisi link, bukan membuang energi untuk spesifikasi atau dokumentasi path
4. Jangan hardcode penamaan URI atau hierarki yang tetap
- Klien tidak boleh menebak atau mengunci struktur namespace server; arahkan navigasi berbasis link
5. Jangan mengekspos tipe resource (klasifikasi internal)
- Tipe objek internal tidak bermakna bagi klien; cukup ekspos media type dan link standar
6. Cukup butuh bookmark (URI awal), sisanya dijelajahi lewat link dalam respons
- Klien hanya perlu mengetahui media type standar, dan transisi status harus selalu dilakukan berdasarkan hyperlink dalam respons server

Penafsiran aturan dan penerapannya di dunia nyata

Agar mendekati RESTful yang sesungguhnya, coupling terhadap protokol, URI, dan tipe harus diminimalkan
API harus berfokus pada format data dan link (media type), sementara struktur URI atau aturan penamaan tidak perlu diketahui sebelumnya oleh klien
Misalnya, alih-alih menspesifikasikan path seperti /users/123/activate, tindakan harus dipandu lewat link "activate" di dalam respons

Mengapa API RESTful sejati jarang ditemui

Kemudahan alat seperti OpenAPI dan Swagger lebih diprioritaskan di lingkungan pengembangan
- Menawarkan manfaat nyata seperti dokumentasi otomatis, pembuatan kode, dan validasi
Di lingkungan SPA, ketika klien dan server dikembangkan oleh tim yang sama, kebutuhan untuk mengatasi masalah coupling URI tidak terlalu besar, sehingga keunggulan HATEOAS kurang menonjol
Beban awal untuk mempelajari prinsip REST serta kompleksitas parsing link dinamis menjadi hambatan praktis yang cukup besar

Kesimpulan

Menurut aturan Fielding, API RESTful yang sejati mensyaratkan penjelajahan dinamis berbasis hipermedia (HATEOAS)
REST bukan sekadar mengimplementasikan CRUD di atas HTTP, melainkan arsitektur yang berfokus pada loose coupling, kemampuan berevolusi, dan transisi status dinamis, seperti prinsip web itu sendiri
Dalam kenyataan, desain yang sesuai dengan kepraktisan dan situasi tim bisa jadi lebih penting
- Untuk API publik bagi pengembang eksternal, adopsi HATEOAS layak direkomendasikan, tetapi untuk API internal, gaya RPC yang sederhana juga bisa lebih praktis
Kunci desain API adalah membuatnya mudah dipelajari dan sulit disalahgunakan, dan tidak harus selalu RESTful

1 komentar

GN⁺ 2025-07-10

Komentar Hacker News

Saya paham dengan fundamentalisme berlebihan yang muncul di sini dan juga membaca makalah Fielding dengan minat, tetapi rasanya ini perang yang sudah selesai. Begitu mendengar istilah REST API, kita hampir bisa yakin akan hal-hal berikut:
- API mengembalikan JSON
- Operasi CRUD dipetakan ke POST/GET/PUT/DELETE
- Tim akan berdebat tanpa henti soal kode status HTTP yang tepat, dan sebagian kode akan dipakai tidak sesuai spesifikasi
- Ada kemungkinan endpoint listing diubah menjadi POST demi mendukung filter yang kompleks Seperti Agile, CI, atau DevOps, kita bisa bersikeras pada definisi awalnya, atau menerima bahwa makna sosialnya sudah berubah dan memakai istilah itu sesuai arti yang lazim dipakai
- Saya pikir alasan Fielding “menang” justru karena logikanya kontradiktif dan sebagian besar salah; ini adalah paradigma "worse is better" abad ke-21. Sistem RPC punya usability yang buruk dan tidak berhasil, misalnya Sun RPC, RMI, DCOM, CORBA, XML-RPC, SOAP, dan Protocol Buffers. Orang bilang REST bukan RPC, tetapi kenyataannya di Javascript kita membuat fungsi seperti
```
const getItem = async (itemId) => { ... }
```
dan fungsi ini memanggil
```
GET /item/{item_id}
```
Di backend ada fungsi seperti
```
Item getItem(String itemId) { ... }
```
dan mapping URL dijelaskan dengan annotation. Pada akhirnya ini tetap RPC. Hanya saja, alih-alih sistem yang rumit dan tidak intuitif, bentuknya lebih manual dan masih bisa dikendalikan developer. Delapan puluh persen dari sebagian besar masalah terjadi karena orang tidak memakai format tanggal ISO 8601
- Saya benar-benar tidak paham kenapa ada orang yang menganggap ini sebagai “pertarungan” dan begitu peduli. Konsep REST itu berguna, tetapi bagian HATEOAS nyaris tidak praktis dan hanya menimbulkan masalah. Kalau melihat Richardson maturity model, puncak tertinggi REST mencakup elemen seperti HATEOAS. Saya juga tidak paham logika bahwa tanpa HATEOAS itu tidak bisa disebut REST, karena perbedaannya tidak terlalu besar. Jika HATEOAS secara praktis hampir tidak berarti, rasanya tidak ada gunanya terobsesi pada klasifikasi yang puritan seperti ini. Richardson maturity model
- Pada bagian “tim terlalu banyak berdebat soal status code dan sering memakainya tidak sesuai HTTP spec”, saya ingin menekankan bahwa 401 Unauthorized harus dipakai untuk kasus belum terautentikasi, sedangkan 403 Forbidden untuk kasus tidak punya otorisasi
- Saya biasanya bertanya pada orang apakah mereka benar-benar akan memakai arti REST seperti yang didefinisikan di paper. Biasanya saya termasuk pihak yang tidak menerima penyalahgunaan istilah yang tidak bermakna. Pada akhirnya saya hanya bilang, “oh, jadi maksudnya web API biasa,” lalu lanjut. Yang penting adalah memahami keanehan masing-masing API itu
- Nuansa yang benar-benar penting bagi saya adalah bahwa “hypermedia link” memang tampak “umum” melalui berbagai link type (di header HTTP atau hasil respons), tetapi secara praktik REST masa kini tetap bekerja sama saja. Misalnya, jika ternyata desainnya salah dan seharusnya enable bukan activate, akhirnya tetap harus diubah dari /api/v1/account/ID/activate menjadi /api/v2/account/ID/enable. Artinya, makna semua aksi di API tetap harus di-hardcode di suatu tempat (dan metadata tambahan seperti ikon, terjemahan deskripsi aksi, dan sebagainya juga kurang). “Generalisasi” dalam pendekatan ini sebenarnya ilusi
Ketika 13 tahun lalu saya pertama kali harus mengembangkan HTTP API, saya membaca makalah Fielding dari awal sampai akhir untuk memahami apa itu REST yang “sebenarnya”, dan juga membaca RESTful Web Services Cookbook. Lalu saya membuat REST API sambil menghindari konvensi Django. Itu semacam pendekatan “cargo cult”, karena saya sendiri tidak benar-benar tahu manfaat apa yang dibawa REST sejati untuk layanan kami. Baru setelah beberapa tahun lagi membuat berbagai HTTP API, saya sadar bahwa dalam praktik kerja nyata, teori murni REST tidak memberi keuntungan apa pun. Visi tentang “self-discovery” dan “kompatibel dengan generic client” hampir mustahil terwujud, dan secara spesifik makalah Fielding pun tidak benar-benar memberi panduan lengkap untuk hal-hal seperti ini. Untuk membuat API yang benar-benar self-discoverable, kita butuh aturan konkret seperti “protokol discovery endpoint”, “deskripsi operasi”, “pesan bantuan”, dan sebagainya. Dan pada akhirnya kita tetap harus membuat client khusus yang memahami aturan itu, sehingga manfaat generic client pun hilang. Artinya, di dunia nyata kita tetap tidak punya pilihan selain membuat kode yang disesuaikan per server, baik berupa API khusus layanan, kode JS, CLI, dan sebagainya. UX yang baik juga bertabrakan dengan idealisme REST, karena untuk UX yang benar-benar baik kita tetap harus menulis kode yang spesifik untuk aplikasi di frontend. Elemen UI memang bisa distandardisasi, tetapi dalam praktiknya lebih berguna membangun UI secara fleksibel lewat bahasa seperti JavaScript
- Saya setuju dengan keterbatasan konsep API yang self-discoverable. Client REST sejati secara praktik mustahil diimplementasikan. Client harus tahu perilaku semua URL, dan jika ada aksi baru yang ditambahkan (misalnya: /cansofspam/123/frobnicate), client tidak bisa menanganinya dengan jelas. Pada akhirnya client harus di-update, atau mengabaikannya, atau paling jauh hanya menambahkan tombol yang sangat sederhana (misalnya: Frobnicate). Karena itu, server atau client REST dalam arti yang sepenuhnya murni sebenarnya tidak ada. Secara realistis yang berjalan adalah client hanya mendukung API yang memang sudah diharapkan, tanpa discovery
- API punya banyak aspek sehingga sulit dijelaskan. Pengguna API juga harus tahu hal-hal seperti latensi respons rata-rata, kode error yang bisa di-retry, atomicity/idempotency dari suatu aksi, dan lain-lain. HATEOAS saja tidak bisa menyampaikan hal-hal itu. Kita tidak perlu mengimplementasikan REST secara sempurna, dan pada dasarnya keuntungan REST hanya sebatas adanya bahasa yang seragam untuk memetakan noun/verb ke method HTTP dan URL. Meski begitu, detail desain dan pertimbangannya tetap sangat banyak. Misalnya, ada hal yang diperbolehkan oleh spesifikasi HTTP tetapi tidak bisa dipakai pada LB nyata, atau kita harus memikirkan kriteria retry untuk error 500 dan logika backoff
- Browser justru adalah “generic code” itu sendiri, yang memberi UX terbaik yang kita pakai setiap hari. Dalam konsep REST, server juga bisa mengirimkan kode ke client (meski ada isu keamanan, browser dan standar web sudah banyak menyelesaikan bagian ini). Tautan ke bagian terkait dalam makalah Fielding
- Sebenarnya bahkan definisi REST versi yang sudah dilemahkan pun tidak memberi banyak keuntungan. Bahwa “untuk menghapus resource harus wajib pakai DELETE” itu tidak terlalu penting. Kalau pakai POST saja, memangnya siapa yang kesulitan?
- Saya bahkan tidak pernah menganggap “self-discoverable” sebagai tujuan, dan juga tidak melihatnya sebagai sesuatu yang bisa dicapai. Untuk desain client yang sederhana, ekspektasinya sejak awal sudah terlalu tinggi. Terlebih lagi, bahkan di TFA kata ‘discoverable’ sendiri tidak muncul
Tempat di mana gaya desain API seperti ini benar-benar berguna adalah ketika pengguna dan agent yang menjelajah atas namanya (misalnya browser) dapat menelusuri API dan berinteraksi sesuai media type dan informasi link di setiap respons. Sebagian besar web API bukan untuk use case seperti ini, melainkan dirancang untuk web app yang mengejar UI/UX tertentu. Ini adalah arah yang dipilih secara sengaja. Pembuat aplikasi ingin mengontrol penuh representasi data, alur UI, dan sebagainya demi tujuan aplikasi mereka. Desain REST API dibutuhkan ketika pengguna perlu punya kontrol yang lebih aktif atas cara memakai resource dari API. Contohnya:
- portal informasi pemerintah yang bisa diakses siapa saja (undang-undang, cuaca, catatan properti, dll.)
- portal pemerintah yang mengharuskan pengisian dan pengajuan berbagai formulir
- proyek open data seperti Wikipedia atau OpenStreetMap Bidang seperti itulah yang seharusnya mengadopsi desain REST API. Pada akhirnya, orang yang ketat soal definisi REST biasanya punya latar belakang akademis, sedangkan yang memakainya secara longgar cenderung developer yang lebih mementingkan pengalaman aplikasi. Jawabannya sederhana: kalau itu bukan REST yang sesungguhnya, ya jangan sebut REST
- Sebenarnya dokumen HTML adalah contoh yang persis seperti itu. Di dalam dokumen ada link ke dokumen lain, dan pengguna bisa menavigasi ke mana saja berdasarkan teks pada link tersebut. Kalau ditujukan untuk manusia, kita menyebutnya UI; kalau untuk aplikasi, kita menyebutnya API. HATEOAS terasa janggal karena seolah-olah API ingin disesuaikan langsung untuk pengguna, padahal kita sudah menikmati hal itu dalam bentuk UI
- Konsep REST murni sangat akademis. Dalam proyek open data/big data, untuk mewujudkan performa atau arsitektur yang benar-benar berguna, pendekatan realistis lebih penting daripada sekadar apakah REST tercapai atau tidak. Bahkan akademisi pun pada akhirnya harus menghasilkan sesuatu, jadi mereka juga tidak bisa bersikeras hanya pada REST yang sempurna
- Desain API seperti ini berguna bukan hanya untuk web page tetapi juga saat membuat client lain. Kita bisa mengambil resource dengan GET, mengekstrak nilai lewat field/path, lalu membuat URI baru untuk dimanipulasi, dan dari pola serupa itu membangun berbagai aplikasi/CLI/UI. Kalau non-SPA, implementasi langsung dengan HTML pun memungkinkan, dan pada akhirnya pengguna (atau user-agent) melakukan dereference terhadap informasi di dalam representasi yang dikembalikan
- Saya penasaran apakah use case ini akan jadi lebih penting ketika era AI yang mengonsumsi API benar-benar datang. Discoverability API jauh lebih menguntungkan bagi AI dibanding web app developer. Dari MCP (protokol kendali imersif) kita bisa melihat betapa kuatnya tool discoverability. HATEOAS bisa memberi keuntungan potensial besar untuk konsumsi bare API seperti ini juga
- Tautan dokumentasi API layanan RESTful National Weather Service AS, misalnya, sangat menyenangkan dipakai jika API informasi publik dirancang dengan baik
Terkait pernyataan bahwa “beban kognitif awal untuk membuat client yang benar-benar berbasis hypermedia terasa sangat besar, dan rasanya jauh lebih nyaman meng-hardcode URI template (/users/{id}/orders dan seterusnya)”, saya merasakan secara empiris bahwa itu memang lebih mudah. Prinsip REST yang ortodoks punya rasio biaya-manfaat yang buruk di sebagian besar situasi. Ini seperti microwave yang memaksa satu tombol untuk mengatur menu/cara kerja/waktu sekaligus, yang jauh lebih merepotkan dibanding sekadar memakai tombol standar yang fungsinya sudah familiar. Pembaca kode mesin dua tombol yang saya pakai di dunia nyata pun absurdly tidak nyaman dioperasikan. Budaya yang masih mengharuskan orang membaca makalah Fielding terasa cukup problematis. Kalau memang ide itu bagus, seharusnya bisa dijelaskan dengan mudah dari berbagai sudut pandang yang populer. Misalnya, tidak ada orang yang bilang bahwa untuk memahami fisika kita harus membaca Principia karya Newton
Agar pola RESTful/HATEOAS benar-benar bernilai saat diadopsi, perlu ada client yang memahaminya. htmx: hypermedia clients intercoolerjs: hatoeas-is-for-humans
Desainer UI ingin mengontrol tampilan detail layar. Beberapa aksi yang mungkin pada resource ingin mereka tampilkan sebagai tombol besar, sebagian disembunyikan di menu, dan sebagian mungkin tidak ditampilkan sama sekali di UI. Jika aksi dirender secara dinamis berdasarkan respons API untuk setiap state tertentu, semua aksi akan terlihat seragam. Karena itu saya merasa RESTful API tidak cocok untuk implementasi UI frontend web yang umum
- Ada banyak kekeliruan dalam klaim ini
  1. Desainer UX terlibat sepanjang siklus pengembangan produk dan tidak selalu punya kendali mutlak. Penempatan aksi tertentu di UI terpisah dari "state" aksi itu sendiri. Artinya, jika state membatasi sesuatu, UX juga harus mengikuti batasan itu
  2. Secara arsitektural, kalau pengecekan state dibungkus dengan baik, if (resource.links['action'] !== null) bisa jauh lebih baik daripada if (state === something). Sebagian besar perubahan state tetap butuh validasi di server, dan jika itu hanya diimplementasikan di server, kompleksitas frontend juga bisa lebih rendah. Saya sudah cukup lama mengembangkan aplikasi HATEOAS dan juga mengelola HAL4J. Ada kompleksitasnya, tetapi desain UI itu sendiri bukan hambatan masuknya
- Dalam pengalaman saya, pengembangan “RESTful API” jarang berhubungan langsung dengan UI. Kalau yang dibutuhkan benar-benar hanya UI, API itu sendiri sebenarnya tidak perlu; tinggal pakai pendekatan server-driven saja (seperti DWR zaman dulu)
Saya tidak begitu paham kenapa HATEOAS masih terus dibahas padahal di dunia nyata hampir tidak dipakai. Saya penasaran apakah benar ada tempat yang memakainya, dan client “auto-discovery” seperti apa yang benar-benar tidak perlu tahu informasi server sebelumnya
- Perlu diingat bahwa ACME (protokol Let’s Encrypt) berbasis HATEOAS. Ini pada praktiknya dipakai oleh sebagian besar layanan HTTPS. HTTP sendiri kalau digunakan sebagaimana mestinya pada dasarnya adalah protokol HATEOAS. “Auto-discovery” berarti resource bisa dijelajahi lewat link type atau hal seperti ‘next’. Tentu saja client tetap harus tahu lebih dulu arti dari “next”. LLM juga kuat dalam penelusuran otomatis seperti ini
- Saya pernah memakai HATEOAS dalam sistem pengawasan video kelas enterprise. Ini menyelesaikan masalah versi/hak akses dengan sangat baik di level API. Kami juga memakai beberapa RFC bersama-sama. Namun masalah nomor satu adalah orang mengejar “kenyamanan” dengan cara yang merusak model, dan justru menimbulkan kompleksitas. Selain itu, JSON pada dasarnya bukan format hypertext, jadi ketika kita memaksa HATEOAS ke dalam application/json hasilnya terasa canggung
- Saya sedang menggunakan HATEOAS untuk mengirim komentar ini, dan bahkan sedang membalas komentar sekarang juga. “Client auto-discovery ajaib” yang menangani ini adalah “web browser”
- htmx mungkin adalah upaya yang paling realistis
- Standar seperti OData pun hampir tidak dipakai, dan bahkan tidak terlalu populer. HATEOAS lebih miskin lagi dari sisi popularitas/standar, jadi makin sulit berkembang
Hal yang mudah terlewat dalam diskusi ini adalah tipe konsumen backend API. REST dan HATEOAS biasanya lebih bermakna ketika yang mengonsumsi adalah pihak ketiga yang tidak memiliki backend tersebut secara langsung. Misalnya, konsumen akhir dari halaman HTML tradisional adalah pengguna browser. MCP yang belakangan muncul juga lahir untuk kasus yang membutuhkan “discovery dan interpretasi” atas berbagai JSON RPC API. Sebaliknya, ketika frontend dan backend saling terikat satu banding satu, keuntungan REST tidak terlalu besar dibanding biayanya. Kita perlu membuat dokumentasi/spesifikasi yang lebih generik, dan dalam praktik kerja nyata alat yang sengaja mengabaikan separation of concerns demi produktivitas (seperti trPC) justru kadang lebih berguna. Saat membuat prototipe, integrasi end-to-end juga lebih cepat
- Sangat setuju, dan saya merekomendasikan tulisan HATOEAS is for humans dan htmx: hypermedia clients
- *HATEOAS
Terkait klaim bahwa client penelusuran dinamis dimungkinkan dengan HATEOAS dan schema reference (XSD, JSON Schema, dll.), secara realistis fitur seperti "additionalProperties" dalam JSON schema justru mengulang sumber masalah yang sama. Saya rasa penyampaian dokumentasi secara "out of band" lebih kokoh. Kalau begitu, bagaimana jika di dalam "_links" kita hanya menyediakan satu tautan ke dokumen Swagger, lalu client memproses informasi self path dari sana? Kalau begitu, untuk apa "_links" ada? Jika memang ada client yang mampu menangani dokumen JSON serumit itu, template Swagger dan sejenisnya justru memberi kepadatan informasi dan dinamika yang jauh lebih tinggi. Link CRUD saja tidak cukup untuk menjelaskan keseluruhan API dengan baik, dan mustahil juga menutupi semuanya hanya dengan JSON schema
Kalau cukup disebut HTTP API, semua orang jadi lebih bahagia. REST sendiri sejak awal tidak dirancang untuk API. Dari asalnya, REST adalah untuk sistem informasi yang dikonsumsi manusia, bukan untuk program