Sebagian besar dari apa yang saya pikir saya ketahui tentang REST ternyata salah - dan saya tidak sendiri. Pertanyaan ini memiliki petunjuk yang panjang, tetapi tampaknya perlu karena informasinya agak tersebar. Pertanyaan sebenarnya muncul di bagian akhir jika Anda sudah terbiasa dengan topik ini.
Dari paragraf pertama REST API Roy Fielding harus digerakkan oleh hypertext , cukup jelas dia yakin karyanya disalahartikan secara luas:
Saya merasa frustrasi dengan jumlah orang yang memanggil antarmuka berbasis HTTP apa pun sebagai REST API. Contoh hari ini adalah SocialSite REST API . Itu adalah RPC. Ia berteriak RPC. Ada begitu banyak kopling yang dipamerkan sehingga harus diberi peringkat X.
Fielding melanjutkan dengan mendaftar beberapa atribut REST API. Beberapa dari mereka tampaknya bertentangan dengan praktik umum dan saran umum di SO dan forum lainnya. Sebagai contoh:
REST API harus dimasukkan tanpa pengetahuan sebelumnya di luar URI awal (bookmark) dan kumpulan jenis media standar yang sesuai untuk audiens yang dituju (yaitu, diharapkan dapat dipahami oleh klien mana pun yang mungkin menggunakan API). ...
REST API tidak boleh menentukan nama atau hierarki sumber daya tetap (penggabungan klien dan server yang jelas). ...
REST API harus menghabiskan hampir semua upaya deskriptifnya dalam menentukan jenis media yang digunakan untuk mewakili sumber daya dan mendorong status aplikasi, atau dalam menentukan nama relasi yang diperluas dan / atau markup yang mendukung hypertext untuk jenis media standar yang ada. ...
Ide "hypertext" memainkan peran sentral - lebih dari sekedar struktur URI atau apa arti kata kerja HTTP. "Hypertext" didefinisikan di salah satu komentar:
Ketika saya [Fielding] mengatakan hypertext, yang saya maksud adalah penyajian informasi dan kontrol secara simultan sedemikian rupa sehingga informasi tersebut menjadi kemampuan di mana pengguna (atau robot) memperoleh pilihan dan memilih tindakan. Hypermedia hanyalah perluasan dari arti teks untuk memasukkan jangkar temporal dalam aliran media; kebanyakan peneliti telah menghilangkan perbedaannya.
Hypertext tidak harus berupa HTML di browser. Mesin dapat mengikuti tautan ketika mereka memahami format data dan tipe hubungan.
Saya menebak pada titik ini, tetapi dua poin pertama di atas tampaknya menyarankan bahwa dokumentasi API untuk sumber daya Foo yang terlihat seperti berikut ini mengarah pada hubungan erat antara klien dan server dan tidak memiliki tempat dalam sistem RESTful.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
Sebaliknya, agen harus dipaksa untuk menemukan URI untuk semua Foos dengan, misalnya, mengeluarkan permintaan GET terhadap / foos. (URI tersebut mungkin ternyata mengikuti pola di atas, tetapi bukan itu intinya.) Respons menggunakan jenis media yang mampu menyampaikan cara mengakses setiap item dan apa yang dapat dilakukan dengannya, sehingga memunculkan poin ketiga di atas . Untuk alasan ini, dokumentasi API harus fokus pada penjelasan bagaimana menginterpretasikan hypertext yang terkandung dalam respon.
Selain itu, setiap kali URI ke sumber daya Foo diminta, respons berisi semua informasi yang diperlukan agen untuk menemukan cara melanjutkan, misalnya, mengakses sumber daya terkait dan induk melalui URI mereka, atau dengan mengambil tindakan setelah pembuatan. / penghapusan sumber daya.
Kunci dari keseluruhan sistem adalah bahwa respon terdiri dari hypertext yang terdapat dalam jenis media yang dengan sendirinya menyampaikan ke opsi agen untuk melanjutkan. Ini tidak berbeda dengan cara kerja browser untuk manusia.
Tapi ini hanya tebakan terbaik saya pada saat ini.
Fielding memposting tindak lanjut di mana dia menanggapi kritik bahwa pembahasannya terlalu abstrak, kurang contoh, dan kaya jargon:
Orang lain akan mencoba menguraikan apa yang telah saya tulis dengan cara yang lebih langsung atau dapat diterapkan untuk beberapa masalah praktis saat ini. Saya mungkin tidak akan melakukannya, karena saya terlalu sibuk bergumul dengan topik berikutnya, mempersiapkan konferensi, menulis standar lain, bepergian ke suatu tempat yang jauh, atau hanya melakukan hal-hal kecil yang membuat saya merasa telah mendapatkan gaji saya.
Jadi, dua pertanyaan sederhana untuk pakar REST di luar sana dengan pola pikir praktis: bagaimana Anda menafsirkan apa yang dikatakan Fielding dan bagaimana Anda mempraktikkannya saat mendokumentasikan / menerapkan REST API?
Sunting: pertanyaan ini adalah contoh betapa sulitnya mempelajari sesuatu jika Anda tidak memiliki nama untuk apa yang Anda bicarakan. Nama dalam hal ini adalah "Hypermedia sebagai Mesin Negara Aplikasi" (HATEOAS).