Apakah ada standar atau praktik terbaik untuk menyusun respons JSON dari API? Jelas, setiap data aplikasi berbeda, sehingga banyak yang tidak saya pedulikan, melainkan "respons boilerplate", jika Anda mau. Contoh yang saya maksud:
Permintaan yang berhasil:
{
"success": true,
"payload": {
/* Application-specific data would go here. */
}
}
Permintaan gagal:
{
"success": false,
"payload": {
/* Application-specific data would go here. */
},
"error": {
"code": 123,
"message": "An error occurred!"
}
}
Jawaban:
Ya, ada beberapa standar (meskipun beberapa kebebasan pada definisi standar) yang telah muncul:
Ada juga format deskripsi API JSON:
sumber
Panduan Google JSON
Respon keberhasilan kembali
data
Kembali respons kesalahan
error
dan jika klien Anda adalah JS, Anda dapat menggunakannya
if ("error" in response) {}
untuk memeriksa apakah ada kesalahan.sumber
error
, halaman Google memberikan contohnyaSaya kira standar de facto belum benar-benar muncul (dan mungkin tidak pernah). Tapi bagaimanapun, ini adalah pendapat saya:
Permintaan yang berhasil:
Permintaan gagal:
Keuntungan: Elemen tingkat atas yang sama dalam kasus sukses dan kesalahan
Kekurangan: Tidak ada kode kesalahan, tetapi jika Anda mau, Anda bisa mengubah status menjadi kode (berhasil atau gagal), -atau- Anda bisa menambahkan item tingkat atas lain bernama "kode".
sumber
messages
yang merupakan array pesan bukannya string tunggal.fail
untuk masalah validasi tipikal, sementaraerror
hanya digunakan dengan fatals seperti kesalahan db.200
di header mengapa Anda membutuhkanstatus
bidang? cukup kembalikan objek data secara langsung. Anda tahu ini dapat menyebabkan rasa sakit tambahan dengan bahasa FE yang diketik seperti TypeScript.Dengan asumsi pertanyaan Anda adalah tentang desain layanan web REST dan lebih tepatnya tentang keberhasilan / kesalahan.
Saya pikir ada 3 jenis desain.
Gunakan hanya kode Status HTTP untuk menunjukkan jika ada kesalahan dan coba batasi diri Anda dengan yang standar (biasanya sudah cukup).
Gunakan Status HTTP + json body (bahkan jika itu adalah kesalahan). Tetapkan struktur yang seragam untuk kesalahan (mis: kode, pesan, alasan, jenis, dll) dan gunakan untuk kesalahan, jika itu berhasil maka kembalikan saja respons json yang diharapkan.
Lupakan status http (mis: selalu status 200), selalu gunakan json dan tambahkan di root dari respons, boolean responseValid dan objek kesalahan (kode, pesan, dll.) Yang akan diisi jika itu adalah kesalahan jika tidak maka bidang lainnya (sukses) dihuni.
Pro: Klien hanya berurusan dengan tubuh respons yang merupakan string json dan mengabaikan status (?).
Cons: Standar kurang.
Terserah Anda untuk memilih :)
Tergantung pada API saya akan memilih 2 atau 3 (saya lebih suka 2 untuk json rest apis). Hal lain yang saya alami dalam merancang REST Api adalah pentingnya dokumentasi untuk setiap sumber daya (url): parameter, tubuh, respons, header dll + contoh.
Saya juga akan merekomendasikan Anda untuk menggunakan jersey (implementasi jax-rs) + genson (perpustakaan penyatuan data java / json). Anda hanya perlu melepaskan jersey genson + di classpath Anda dan json didukung secara otomatis.
EDIT:
Solusi 2 adalah yang paling sulit untuk diterapkan tetapi keuntungannya adalah Anda dapat menangani pengecualian dengan baik dan tidak hanya kesalahan bisnis, upaya awal lebih penting tetapi Anda menang dalam jangka panjang.
Solusi 3 adalah mudah diimplementasikan pada kedua sisi server dan klien tetapi tidak begitu baik karena Anda harus merangkum objek yang ingin Anda kembalikan dalam objek respons yang juga berisi kesalahan responseValid +.
sumber
The RFC 7807: Soal Rincian untuk HTTP API adalah pada saat ini hal yang paling dekat kita harus standar resmi.
sumber
Berikut ini adalah format instagram json yang digunakan
sumber
Saya tidak akan sombong untuk mengklaim bahwa ini adalah standar sehingga saya akan menggunakan formulir "Saya lebih suka".
Saya lebih suka respon singkat (ketika meminta daftar / artikel saya ingin array artikel JSON).
Dalam desain saya, saya menggunakan HTTP untuk laporan status, 200 mengembalikan hanya payload.
400 mengembalikan pesan tentang apa yang salah dengan permintaan:
Kembali 404 jika model / pengontrol / URI tidak ada
Jika ada kesalahan dengan pemrosesan di sisi saya, saya mengembalikan 501 dengan pesan:
Dari apa yang saya lihat cukup banyak kerangka ISTIRAH cenderung sepanjang garis ini.
Alasan :
JSON seharusnya merupakan format payload , ini bukan protokol sesi. Seluruh gagasan payload sesi-ish verbose berasal dari dunia XML / SOAP dan berbagai pilihan salah arah yang menciptakan desain-desain besar itu. Setelah kami menyadari semua itu adalah sakit kepala besar, inti dari REST / JSON adalah untuk KISS, dan mematuhi HTTP. Saya tidak berpikir bahwa ada sesuatu yang jauh standar di kedua JSend dan terutama tidak dengan yang lebih banyak di antara mereka. XHR akan bereaksi terhadap respons HTTP, jika Anda menggunakan jQuery untuk AJAX Anda (seperti umumnya), Anda dapat menggunakan
try
/catch
dandone()
/fail()
callback untuk menangkap kesalahan. Saya tidak bisa melihat bagaimana merangkum laporan status di JSON lebih berguna dari itu.sumber
Untuk apa nilainya, saya melakukan ini secara berbeda. Panggilan yang berhasil hanya memiliki objek JSON. Saya tidak memerlukan objek JSON tingkat lebih tinggi yang berisi bidang keberhasilan yang menunjukkan bidang benar dan muatan yang memiliki objek JSON. Saya baru saja mengembalikan objek JSON yang sesuai dengan 200 atau apa pun yang sesuai dalam kisaran 200 untuk status HTTP di header.
Namun, jika ada kesalahan (sesuatu dalam 400 keluarga) saya mengembalikan objek kesalahan JSON yang terbentuk dengan baik. Sebagai contoh, jika klien mem-POSTing Pengguna dengan alamat email dan nomor telepon dan salah satunya rusak (yaitu saya tidak bisa memasukkannya ke dalam basis data saya) saya akan mengembalikan sesuatu seperti ini:
Bit penting di sini adalah bahwa properti "bidang" harus cocok dengan bidang JSON persis yang tidak dapat divalidasi. Ini memungkinkan klien untuk mengetahui apa yang salah dengan permintaan mereka. Juga, "pesan" ada di lokasi permintaan. Jika kedua "alamat email" dan "nomor telepon" tidak valid maka array "kesalahan" akan berisi entri untuk keduanya. Badan respons JSON 409 (Konflik) mungkin terlihat seperti ini:
Dengan kode status HTTP dan JSON ini, klien memiliki semua yang mereka butuhkan untuk merespons kesalahan dengan cara yang deterministik dan tidak membuat standar kesalahan baru yang mencoba menyelesaikan menggantikan kode status HTTP. Catatan, ini hanya terjadi untuk kisaran 400 kesalahan. Untuk apa pun dalam kisaran 200 saya hanya bisa mengembalikan apa pun yang sesuai. Bagi saya itu sering merupakan objek JSON seperti HAL tapi itu tidak terlalu penting di sini.
Satu hal yang saya pikirkan tentang menambahkan adalah kode kesalahan numerik baik dalam entri array "kesalahan" atau root dari objek JSON itu sendiri. Tapi sejauh ini kami belum membutuhkannya.
sumber
Tidak ada kesepakatan tentang format respons api sisanya dari raksasa perangkat lunak besar - Google, Facebook, Twitter, Amazon, dan lainnya, meskipun banyak tautan telah disediakan dalam jawaban di atas, di mana beberapa orang telah mencoba untuk membakukan format respons.
Karena kebutuhan API dapat berbeda, sangat sulit untuk mengajak semua orang bergabung dan menyetujui beberapa format. Jika Anda memiliki jutaan pengguna yang menggunakan API Anda, mengapa Anda mengubah format respons Anda?
Berikut ini adalah pendapat saya tentang format respons yang terinspirasi oleh Google, Twitter, Amazon, dan beberapa posting di internet:
https://github.com/adnan-kamili/rest-api-response-format
Menyombongkan file:
https://github.com/adnan-kamili/swagger-sample-template
sumber
Inti dari JSON adalah bahwa ia sepenuhnya dinamis dan fleksibel. Tekuk sesuai keinginan Anda, karena itu hanya satu set objek dan array JavaScript berseri, yang di-root dalam satu node.
Apa jenis rootnode terserah Anda, apa isinya terserah Anda, apakah Anda mengirim metadata beserta responsnya terserah Anda, apakah Anda menyetel tipe mime ke
application/json
atau membiarkannya sepertitext/plain
terserah Anda ( selama Anda tahu cara menangani kasing tepi).Bangun skema ringan yang Anda sukai.
Secara pribadi, saya telah menemukan bahwa pelacakan analitik dan penyajian mp3 / ogg dan penyajian galeri gambar serta perpesanan teks dan paket jaringan untuk game online, dan posting blog dan komentar blog semuanya memiliki persyaratan yang sangat berbeda dalam hal apa yang ada. dikirim dan apa yang diterima dan bagaimana mereka harus dikonsumsi.
Jadi hal terakhir yang saya inginkan, ketika melakukan semua itu, adalah mencoba untuk membuat masing-masing sesuai dengan standar boilerplate yang sama, yang didasarkan pada XML2.0 atau semacamnya.
Yang mengatakan, ada banyak yang bisa dikatakan untuk menggunakan skema yang masuk akal bagi Anda dan dipikirkan dengan baik.
Cukup baca beberapa respons API, catat apa yang Anda suka, kritik apa yang tidak Anda sukai, tuliskan kritik itu dan pahami mengapa mereka salah, dan kemudian pikirkan tentang bagaimana menerapkan apa yang Anda pelajari pada apa yang Anda butuhkan.
sumber
JSON-RPC 2.0 mendefinisikan format permintaan dan respons standar, dan menghirup udara segar setelah bekerja dengan REST API.
sumber
code
bidang tersebut menjadi sebuah String. Untungnya spec memungkinkan kita untuk memasukkan informasi apa pun yang kita inginkan ke dalamdata
bidang kesalahan . Dalam proyek JSON-RPC saya, saya biasanya menggunakan kode numerik tunggal untuk untuk semua kesalahan lapisan aplikasi (sebagai lawan dari salah satu kesalahan protokol standar). Lalu saya menaruh informasi kesalahan terperinci (termasuk kode string yang menunjukkan jenis kesalahan nyata) didata
bidang.Bagi mereka yang datang kemudian, selain jawaban yang diterima yang mencakup HAL, JSend, dan JSON API, saya akan menambahkan beberapa spesifikasi lain yang layak dilihat:
sumber
Kerangka dasar yang disarankan terlihat baik-baik saja, tetapi objek kesalahan seperti yang didefinisikan terlalu terbatas. Orang sering kali tidak dapat menggunakan nilai tunggal untuk mengungkapkan masalah, dan sebagai gantinya diperlukan rantai masalah dan sebab .
Saya melakukan sedikit riset dan menemukan bahwa format yang paling umum untuk kesalahan pengembalian (pengecualian) adalah struktur dari formulir ini:
Ini adalah format yang diusulkan oleh standar data OASIS OASIS OData dan tampaknya menjadi opsi paling standar di luar sana, namun tampaknya tidak ada tingkat adopsi yang tinggi dari standar apa pun pada saat ini. Format ini konsisten dengan spesifikasi JSON-RPC.
Anda dapat menemukan pustaka sumber terbuka lengkap yang mengimplementasikannya di: Mendocino JSON Utilities . Pustaka ini mendukung Objek JSON serta pengecualian.
Detailnya dibahas dalam posting blog saya tentang Penanganan Kesalahan di API JSON REST
sumber
Tidak ada standar yang melanggar hukum atau melarang selain akal sehat. Jika kita mengabstraksikan ini seperti dua orang berbicara, standar adalah cara terbaik mereka dapat secara akurat memahami satu sama lain dalam kata-kata minimum dalam waktu minimum. Dalam kasus kami, 'kata-kata minimum' adalah mengoptimalkan bandwidth untuk efisiensi transportasi dan 'memahami secara akurat' adalah struktur untuk efisiensi parser; yang akhirnya berakhir dengan semakin sedikit data, dan struktur umum; sehingga dapat melewati lubang pin dan dapat diurai melalui lingkup umum (setidaknya pada awalnya).
Hampir dalam setiap kasus yang disarankan, saya melihat respons terpisah untuk skenario 'Sukses' dan 'Kesalahan', yang merupakan semacam ambiguitas bagi saya. Jika tanggapan berbeda dalam kedua kasus ini, lalu mengapa kita benar-benar perlu memasang bendera 'Sukses' di sana? Tidakkah jelas bahwa tidak adanya 'Kesalahan' adalah 'Sukses'? Mungkinkah memiliki respons di mana 'Sukses' BENAR dengan set 'Kesalahan'? Atau bagaimana, 'Sukses' itu SALAH tanpa set 'Kesalahan'? Hanya satu bendera saja tidak cukup? Saya lebih suka memiliki bendera 'Kesalahan' saja, karena saya percaya akan ada lebih sedikit 'Kesalahan' daripada 'Sukses'.
Juga, haruskah kita benar-benar membuat 'Galat' menjadi bendera? Bagaimana jika saya ingin merespons dengan beberapa kesalahan validasi? Jadi, saya merasa lebih efisien untuk memiliki simpul 'Kesalahan' dengan setiap kesalahan sebagai anak dari simpul itu; di mana simpul 'Kesalahan' kosong (dihitung ke nol) akan menunjukkan 'Sukses'.
sumber
Respons Terbaik untuk apis web yang dapat dengan mudah dipahami oleh pengembang seluler.
Ini untuk Respon "Sukses"
Ini untuk Respons "Kesalahan"
sumber