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!"
  }
}

Ya, ada beberapa standar (meskipun beberapa kebebasan pada definisi standar) yang telah muncul:

1. API JSON - API JSON mencakup pembuatan dan pembaruan sumber daya juga, bukan hanya tanggapan.
2. JSend - Sederhana dan mungkin apa yang sudah Anda lakukan.
3. OData JSON Protocol - Sangat rumit.
4. HAL - Suka OData tetapi bertujuan untuk menjadi seperti HATEOAS .

Ada juga format deskripsi API JSON:

• Kesombongan
  • Skema JSON (digunakan oleh kesombongan tetapi Anda bisa menggunakannya sendiri)
• WADL di JSON
• RAML
• HAL karena HATEOAS dalam teori adalah menggambarkan diri.

Panduan Google JSON

Respon keberhasilan kembali data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

Kembali respons kesalahan error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

dan jika klien Anda adalah JS, Anda dapat menggunakannya if ("error" in response) {}untuk memeriksa apakah ada kesalahan.

Saya kira standar de facto belum benar-benar muncul (dan mungkin tidak pernah). Tapi bagaimanapun, ini adalah pendapat saya:

Permintaan yang berhasil:

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

Permintaan gagal:

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

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".

Dengan asumsi pertanyaan Anda adalah tentang desain layanan web REST dan lebih tepatnya tentang keberhasilan / kesalahan.

Saya pikir ada 3 jenis desain.

1. Gunakan hanya kode Status HTTP untuk menunjukkan jika ada kesalahan dan coba batasi diri Anda dengan yang standar (biasanya sudah cukup).

   • Pro: Ini adalah standar yang tidak tergantung pada api Anda.
   • Cons: Kurang informasi tentang apa yang sebenarnya terjadi.

2. 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.

   • Pro: Masih standar saat Anda menggunakan kode status HTTP yang ada dan Anda mengembalikan json yang menjelaskan kesalahan (Anda memberikan informasi lebih lanjut tentang apa yang terjadi).
   • Cons: Output json akan bervariasi tergantung apakah itu kesalahan atau keberhasilan.

3. 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 +.

The RFC 7807: Soal Rincian untuk HTTP API adalah pada saat ini hal yang paling dekat kita harus standar resmi.

Berikut ini adalah format instagram json yang digunakan

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}

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:

{"message" : "Missing parameter: 'param'"}

Kembali 404 jika model / pengontrol / URI tidak ada

Jika ada kesalahan dengan pemrosesan di sisi saya, saya mengembalikan 501 dengan pesan:

{"message" : "Could not connect to data store."}

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/ catchdan done()/ fail()callback untuk menangkap kesalahan. Saya tidak bisa melihat bagaimana merangkum laporan status di JSON lebih berguna dari itu.

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:

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

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:

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

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.

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

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/jsonatau membiarkannya seperti text/plainterserah 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.

JSON-RPC 2.0 mendefinisikan format permintaan dan respons standar, dan menghirup udara segar setelah bekerja dengan REST API.

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:

• JSON-LD , yang merupakan Rekomendasi W3C dan menentukan cara membangun Layanan Web yang dapat dioperasikan di JSON
• Tipe Ion Hypermedia untuk REST, yang mengklaim dirinya sebagai "tipe hypermedia berbasis JSON yang sederhana dan intuitif untuk REST"

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:

{
   "success": false,
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

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

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'.

Respons Terbaik untuk apis web yang dapat dengan mudah dipahami oleh pengembang seluler.

Ini untuk Respon "Sukses"

{  
   "ReturnCode":"1",
   "ReturnMsg":"Successfull Transaction",
   "ReturnValue":"",
   "Data":{  
      "EmployeeName":"Admin",
      "EmployeeID":1
   }
}

Ini untuk Respons "Kesalahan"

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}