Haruskah saya menggunakan WADL untuk menggambarkan API SISA saya?

Saya akan memulai proyek yang menggunakan pendekatan RESTful dengan benar. Artinya, ia menggunakan HATEOAS dan menyajikan sumber daya dengan cara yang memungkinkan untuk eksplorasi umum oleh klien.

Saya ingin memastikan bahwa saya memberikan deskripsi tentang titik akhir saya dengan cara yang memungkinkan aplikasi klien dihasilkan secara otomatis dalam berbagai bahasa. Saya mengerti bahwa untuk layanan web berbasis SOAP saya dapat menggunakan WSDL dan yang tampaknya ada WSDL2 yang memberikan definisi yang lebih besar dari kata kerja HTTP yang digunakan dengan REST. Namun saya melihat banyak artikel berayun-ayun di atas utilitas itu.

Jadi, haruskah saya menggunakan WADL untuk memungkinkan generator kode eksternal dengan cepat membangun klien untuk aplikasi web saya atau adakah standar yang lebih baik yang diharapkan?

Saran saya jangan repot-repot. WADL belum diadopsi secara luas. Lihat pertanyaan ini di Stack Overflow dan ada beberapa pandangan kuat bahwa itu tidak cocok dengan jenis REST 'tepat' yang Anda gambarkan, seperti yang ditunjukkan di sini pada pertanyaan Stack Overflow lainnya .

Deskripsi WADL memakan waktu lama untuk dibangun (dan sebagian besar manual) dan mereka menambahkan kerapuhan yang harus dihindari oleh HATEOAS - yaitu, Anda akan memiliki beberapa titik masuk yang terdefinisi dengan baik tetapi persis bagaimana hasil klien Anda kemudian ditentukan oleh tautan buram, bukan yang telah ditentukan sebelumnya 'kontrak'.

Itu tidak berarti Anda harus melarikan diri sepenuhnya dari dokumentasi, definisi skema, dll, meskipun ada akhir dari spektrum RESTifarian yang akan menyarankan Anda dapat mendekati deskripsi diri tingkat tinggi yang Anda tidak butuhkan. Saya tidak menemukan ini menjadi kasus dalam praktek. Beberapa contoh yang dikerjakan dengan baik harus semuanya merupakan kebutuhan pengembang yang tidak dikenal. Dan ketuk beberapa klien untuk API Anda sendiri untuk mencobanya (cukup mudah dari JQuery). Itu akan memberi Anda indikasi yang baik apakah Anda sedang membangun sesuatu yang bisa dikonsumsi atau tidak.

Sumber informasi yang baik di bidang ini adalah Bahasa Aplikasi Hypertext . Saya menemukan beberapa di antaranya sedikit berat, tetapi perdebatan di milis bagus dan terkini dan relevan.

Semoga ini bisa membantu Anda memulai.

Keadaan antarmuka REST sebagai didorong dari apa pun selain browser interaktif tidak terlalu baik. HATEOAS adalah prinsip yang bagus, tetapi mengarah ke antarmuka yang sangat berorientasi pada orang dan cenderung mengarah pada beban antarmuka pengguna yang diletakkan pada pengembang layanan (yang biasanya cukup sibuk membuat layanan itu sendiri berfungsi).

WADL sendiri tidak terlalu bagus; itu tidak benar-benar menangkap cukup semantik layanan untuk memungkinkan alat segalanya. Tentu saja, ini adalah masalah yang sulit pada umumnya. WSDL juga jarang mengekspos informasi yang cukup, dan itu memiliki lebih banyak upaya dimasukkan ke dalam masalah (mungkin untuk melampirkan informasi yang cukup, tetapi hampir tidak ada orang yang melakukannya).

Namun dikatakan bahwa seorang kolega saya telah menghabiskan waktu berbulan-bulan bekerja di perpustakaan yang menggunakan antarmuka REST untuk layanan, dan antarmuka yang dijelaskan WSDL untuk layanan yang sama ^[*] telah diprogram secara otomatis dengan kualitas yang hampir sama dalam hitungan detik; Melanjutkan perjalanan sekitar satu hari menulis kelas pembungkus. Firasat saya (berdasarkan pada ukuran sampel terbatas) adalah bahwa Anda tidak dapat menghilangkan semua kerapuhan dalam layanan yang kompleks karena semantik layanan pasti akan berkembang seiring waktu, dan bahwa REST lebih baik dalam menggerakkan antarmuka untuk manusia sedangkan SOAP lebih baik untuk interface libraries (ada tooling klien WSDL / SOAP yang bagus untuk hampir semua bahasa note). Kecuali Anda memiliki kemewahan melakukan keduanya, yang menjadi fokus Anda harus bergantung pada kelompok klien mana yang paling Anda pedulikan.

Saya tidak akan berusaha keras untuk WADL, tetapi jika kerangka REST Anda akan memproduksinya untuk Anda (Apache CXF melakukan ini) maka tidak ada alasan khusus untuk tidak menyediakannya. Siapa pun yang ingin alat kode Anda akan menginginkan WSDL + SOAP.

^{[*] Sebagai penulis layanan tersebut, saya dapat mengatakan dengan pasti bahwa kedua antarmuka mendukung operasi yang sama - ada model abstrak yang mendasari umum - dan dalam gaya "alami" untuk kedua jenis antarmuka. Di sisi layanan, jelas bahwa beberapa hal lebih mudah dengan REST dan yang lainnya dengan SOAP.}

The W3C telah membuat rekomendasi resmi untuk standar dokumentasi SISA berdasarkan WSDL 2.0 . Berikut ini kutipan dari artikel IBM :

Istilah layanan Web biasanya dikaitkan dengan layanan berbasis operasi atau tindakan menggunakan SOAP dan standar WS *, seperti WS-Addressing dan WS-Security. Istilah layanan Web REST umumnya mengacu pada arsitektur layanan Web berbasis sumber daya yang menggunakan HTTP dan XML. Masing-masing gaya layanan Web arsitektur memiliki tempatnya, tetapi sampai saat ini, standar WSDL tidak sama-sama mendukung kedua gaya. Pengikatan HTTP WSDL 1.1 tidak memadai untuk menggambarkan komunikasi dengan HTTP dan XML, jadi tidak ada cara untuk secara formal menggambarkan layanan Web REST dengan WSDL. Publikasi WSDL 2.0, yang dirancang dengan mempertimbangkan layanan REST Web, sebagai rekomendasi World Wide Web Consortium (W3C) berarti sekarang ada bahasa untuk menggambarkan layanan Web REST.