"Dan kamu percaya padanya?" Kata ombudsman kuku itu dengan nada mencela. "Yah, bagaimana menurutmu, akankah aku mengambil beban ini tanpa seizinmu?"
"Jadi, kamu mengambil beban?" Teriak Ostap. - Kenapa?
- Panikovsky mengatakan bahwa mereka adalah emas.
Ostap memandang Panikovsky. Baru sekarang dia memperhatikan bahwa di balik jaketnya tidak ada bagian depan kemeja yang hanya lima puluh dolar dan dari sana pandangan Tuhan yang telanjang memandangi cahaya siang. Tanpa sepatah kata pun, kombinator hebat itu jatuh ke kursi. Dia bergetar, menangkap tangannya di udara. Kemudian gemuruh gunung berapi keluar dari tenggorokannya, air mata mengalir keluar dari matanya, dan tawa, yang mempengaruhi semua kelelahan malam itu, semua kekecewaan dalam pertarungan dengan Koreiko, begitu menyedihkan diparodikan oleh saudara-saudaranya yang susu.
Dengan penggalan ini dari klasik, saya ingin kata pengantar terjemahan posting blog Roy T. Fielding REST APIs harus didorong oleh hypertext. Terima kasih khusus kepada
habr.com/users/arthuriantech untuk tautan ke materi tersebut.
Minggu ini di Habré ditandai sebagai minggu REST (Lengkap) API. Dalam hal ini, saya selalu bingung dengan keberadaan awalan REST dalam istilah ini. Dan, ternyata, bukan hanya saya. Hari ini saya akan membacanya sendiri dan mengundang semua orang untuk mencari tahu apa yang dipikirkan oleh Roy T. Fielding pada 2008. Tentu saja, seseorang dengan gugup merayap di atas bangku dan berkata: beri tahu Roy, Benya tahu untuk REST API. Namun demikian, kita akan mulai.
Saya kecewa dengan pemikiran berapa banyak orang yang memanggil antarmuka berdasarkan protokol HTTP REST API. Contoh hari ini adalah REST SocialSite API. Ini adalah RPC. Ini adalah RPC terang-terangan. Ini menunjukkan hubungan keras sehingga inilah saatnya baginya untuk menetapkan kategori porno keras.
Apa yang perlu dilakukan agar mereka memahami bahwa hypertext adalah elemen yang diperlukan dalam arsitektur REST? Dengan kata lain, jika mekanisme status aplikasi (dan karenanya API) tidak berbasis hiperteks, itu tidak bisa tenang dan tidak bisa menjadi API tenang. Intinya. Buku mana yang harus saya tulis ulang untuk memperjelasnya?
Pengembang API, perhatikan aturan berikut sebelum menelepon kreasi API REST Anda:
REST API tidak boleh bergantung pada protokol komunikasi tertentu, meskipun keberhasilan pemetaannya terhadap protokol ini dapat bergantung pada ketersediaan metadata, pilihan metode, dll. Secara umum, protokol apa pun dalam skema URI harus memungkinkan skema URI digunakan untuk identifikasi. [Kesalahan di sini adalah identifikasi tidak terpisah dari interaksi.]
REST API tidak boleh mengandung perubahan apa pun pada protokol komunikasi, kecuali mengisi atau memperbaiki rincian bit protokol standar yang tidak didefinisikan dengan tepat, seperti metode PATCH HTTP atau bidang taut Link. Penanganan masalah untuk implementasi yang tidak berfungsi (seperti browser yang cukup bodoh untuk percaya HTML mendefinisikan seperangkat metode HTTP) harus ditentukan secara terpisah atau, setidaknya dalam aplikasi, dengan harapan bahwa penyelesaiannya pada akhirnya akan menjadi usang. [Kesalahan di sini adalah bahwa antarmuka sumber daya spesifik dan tidak universal.]
REST API harus menghabiskan hampir semua upaya deskriptifnya untuk mendefinisikan jenis media yang digunakan untuk mewakili sumber daya, dan mengelola keadaan aplikasi, serta mendefinisikan hubungan yang diperluas dan nama markup dengan dukungan hypertext untuk jenis media standar yang ada. Upaya apa pun yang digunakan untuk menjelaskan metode mana yang akan digunakan untuk kepentingan URI harus sepenuhnya didefinisikan sebagai bagian dari aturan pemrosesan untuk jenis media (dan, dalam banyak kasus, sudah ditentukan oleh jenis media yang ada). [Kesalahan di sini adalah bahwa informasi di luar sumber daya mengendalikan interaksi, bukan hiperteks.]
REST API tidak boleh mendefinisikan nama sumber daya tetap atau ruang nama (konektivitas klien-server ketat). Server harus memiliki kebebasan untuk mengelola ruang nama mereka sendiri. Alih-alih, biarkan server memberi instruksi kepada klien tentang cara membuat URI yang sesuai, misalnya, dalam formulir HTML dan templat URI, mendefinisikan instruksi ini dalam jenis media dan hubungan referensi. [Kesalahan di sini adalah bahwa struktur sumber daya diatur di luar sumber daya ini, misalnya, dalam standar khusus domain, yang sebenarnya merupakan analog dari hubungan fungsional RPC].
API REST seharusnya tidak memiliki "mengetik" sumber daya yang signifikan bagi klien. Spesifikasi penulis dapat menggunakan jenis sumber daya untuk menggambarkan implementasi server di belakang antarmuka, tetapi jenis ini harus tidak relevan dan tidak terlihat oleh klien. Satu-satunya jenis yang penting bagi klien adalah jenis media dari tampilan saat ini dan nama hubungan standar. [lihat di atas]
API REST harus dimasukkan tanpa pengetahuan sebelumnya selain URI awal dan serangkaian jenis media terstandarisasi yang cocok untuk audiens target (mis. Diharapkan di sisi klien, yang dapat menggunakan API). Mulai saat ini, semua transisi status aplikasi harus ditentukan oleh pilihan opsi yang disediakan oleh server yang hadir dalam tampilan yang diterima, atau oleh manipulasi pengguna dengan tampilan ini. Transisi dapat ditentukan (atau dibatasi) oleh pengetahuan klien tentang jenis media dan mekanisme komunikasi sumber daya yang dapat ditingkatkan dengan cepat (misalnya, kode berdasarkan permintaan). [Kesalahan di sini adalah bahwa informasi di luar sumber daya mengendalikan interaksi, bukan hiperteks.]
Mungkin saya melewatkan sesuatu, tetapi aturan di atas adalah yang esensial untuk hypertext, yang paling sering dilanggar dalam apa yang disebut REST API. Cobalah untuk tetap menggunakannya atau pilih kata kunci lain untuk API Anda.
Posting ini oleh Roy T. Fielding memicu diskusi di komentar. Saya mengusulkan untuk berkenalan dengan bagian dari diskusi, yang disertai dengan jawaban penulis.
Pertanyaan:
Dalam pengertian apa Anda menggunakan istilah "hypertext" di sini? Apakah saya harus membaca karya Anda untuk memahami maksud Anda, atau adakah sesuatu yang online yang mengungkapkan makna konsep ini?
Jawabannya adalah:
Saya memiliki slide dalam pembicaraan REST saya yang menjelaskan apa arti hypertext (dan hypermedia).
Hypertext memiliki banyak definisi:
Definisi awal Ted Nelson difokuskan pada dokumen non-linear.
Yang saya maksud dengan "hypertext" adalah dokumen non-linear - sebuah teks yang bercabang dan memungkinkan pembaca untuk membuat pilihan, dokumen yang mudah dibaca di layar interaktif. Secara umum diterima bahwa ini adalah urutan blok teks yang dihubungkan oleh tautan yang menawarkan berbagai rute kepada pembaca. [Theodore H. Nelson]
Hypertext kemudian menjadi terkait dengan mekanisme antarmuka pengguna tertentu.
Hypertext adalah media penyimpanan yang didukung komputer di mana dokumen terkait ditampilkan dengan tautannya pada layar komputer resolusi tinggi. [Jeffrey Conklin]
Ketika saya mengatakan "hypertext", saya maksudkan presentasi simultan dari informasi dan kontrol sedemikian rupa sehingga informasi menjadi tersedia, berkat mana pengguna (atau mesin) mendapatkan pilihan dan memilih tindakan. Hypermedia hanyalah perpanjangan dari arti teks untuk memasukkan jangkar sementara dalam aliran media; kebanyakan peneliti menolak perbedaan ini.
Hypertext tidak harus berupa HTML untuk peramban. Mesin dapat mengikuti tautan ketika mereka memahami format data dan tipe hubungan.
Dave Johnson (penulis API yang dikritik):
Mungkin saya memberikan kata-kata kabur. Saya tidak pernah bermaksud untuk mengklaim bahwa OpenSocial atau SocialSite RPC APIs RESTful. Lebih banyak di blog saya rollerweblogger.org/roller/entry/the_x_rated_socialsite_api .
Jawabannya adalah:
Protokol OpenSocial RESTful bukan RESTful. Ini dapat diperbaiki dengan perubahan yang relatif kecil, tetapi sekarang ini hanya mengemas hasil RPC ke dalam jenis media web yang umum.
API tenang yang benar tampak seperti hypertext. Setiap unit informasi yang dapat dialamatkan membawa alamat, baik secara eksplisit (misalnya, atribut tautan dan id) atau secara implisit (misalnya, diperoleh dari definisi jenis media dan struktur presentasi). Hasil kueri diwakili oleh daftar tautan dengan informasi ringkasan, dan bukan array representasi objek (kueri tidak menggantikan identifikasi sumber daya). Representasi sumber daya mendokumentasikan diri sendiri: klien tidak perlu tahu apakah sumber daya ini adalah seorang OpenSocialist, karena itu hanya mempengaruhi representasi yang diterima.
Pikirkan tentang hal ini dalam Internet. Berapa banyak browser web yang menyadari perbedaan antara sumber daya perbankan online dan wiki? Bukan salah satu dari mereka. Mereka tidak perlu tahu tentang jenis sumber daya. Yang perlu mereka ketahui adalah potensi transisi negara: tautan dan bentuk, dan semantik atau tindakan seperti apa yang tersirat saat melintasi tautan ini. Browser menyajikannya sebagai kontrol antarmuka pengguna yang terpisah sehingga pengguna dapat melihat transisi potensial dan mengantisipasi efek dari tindakan yang dipilih. Bot dapat mengikuti mereka sejauh diketahui bahwa tindakannya aman. Hubungan yang diketik, jenis media tertentu, dan elemen terkait tindakan memberikan panduan yang diperlukan untuk agen otomatis.
Tautan yang bermanfaat:
1.
Versi terjemahan dari habr.com/us/users/arthuriantech2.
Tesis Roy yang sama