Apakah struktur yang harus digunakan oleh respons API

Pokoknya: nyatakan hasil dengan kod status 4xx/5xx, bawa muatan dalam { "data": ..., "meta": ... }, dan beralih kepada sampul error apabila gagal; itu sudah cukup untuk API dalaman, dan hanya platform awam dengan banyak penyepadu memerlukan JSON:API atau OpenAPI.

Singkirkan pilihan terburuk dahulu: sentiasa mengembalikan 200 dengan hasil dalam medan code.

Tiga bentuk

A. Objek tanpa sampul

复制{ "id": 1, "name": "demo", "price": 99 }

Bersih, dan semantik HTTP melakukan kerja (404 ialah 404). Tetapi sebaik sahaja anda memerlukan penomboran halaman, amaran atau id surih, tiada tempat untuk meletakkannya tanpa mengubah kontrak.

B. Sampul stabil

复制{
  "data": { "id": 1, "name": "demo" },
  "meta": { "requestId": "abc", "took": 12 }
}

Muatan dan metadata hidup berasingan, jadi metadata baharu tidak pernah membentuk semula data. Berharga satu tahap penyarangan.

C. Sampul segala-galanya (elakkan)

复制{ "code": 0, "message": "success", "data": {...} }

Bentuknya bukan dosa; amalannya yang dosa. Status 200 untuk setiap hasil bermaksud CDN, gateway, pemutus litar, dasar cubaan semula dan papan pemuka semuanya melihat kejayaan. Setiap amaran kemudian memerlukan penghuraian tersuai.

Saranan

Status HTTP untuk hasil, sampul untuk muatan.

复制{
  "data": { "id": 1, "name": "demo" },
  "meta": { "requestId": "req_8f2a", "took": 12 }
}

复制{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order does not exist or was deleted",
    "details": [{ "field": "id", "issue": "not_found" }]
  },
  "meta": { "requestId": "req_8f2a" }
}

Status 4xx atau 5xx; code stabil dan boleh dibaca mesin; message untuk manusia; details untuk ralat borang pada peringkat medan.

Peraturan keras

1. Titik akhir senarai mesti membawa metadata penomboran halaman. Tanpa total atau kursor tiada penomboran.
2. Senarai kosong mengembalikan [], tidak pernah null. null.map ialah gangguan berulang.
3. Cap masa dalam ISO 8601 dengan offset. Lihat format apa untuk cap masa.
4. Satu konvensyen penamaan. snake_case atau camelCase, ditukar sekali di sempadan.
5. Wang sebagai unit kecil integer atau rentetan. 99.99 tidak tepat dalam titik terapung binari.
6. Jangan kelirukan null dengan tiada. Lihat null atau tinggalkan medan.

Bila hendak mengguna pakai spesifikasi

• Platform awam dengan banyak penyepadu: JSON:API atau OpenAPI serta sampul dikongsi
• API dalaman satu pasukan: sampul di atas sudah cukup
• Kontrak kukuh: Schema dahulu, struktur dijana daripadanya

Spesifikasi menjimatkan perbincangan dan mengurangkan kos pengenalan. Untuk pasukan lima orang, JSON:API biasanya ialah kerja negatif.

Soalan Lazim

Bagaimana saya harus memilih antara objek tanpa sampul dan sampul?

Guna sampul apabila anda memerlukan penomboran halaman, amaran atau requestId, supaya meta boleh berkembang tanpa membentuk semula data. Kembalikan objek tanpa sampul hanya apabila anda tidak memerlukan metadata dan boleh menerima bahawa menambah medan kemudian mengubah kontrak.

Mengapa API tidak boleh sentiasa mengembalikan 200 untuk setiap hasil?

CDN, gateway, pemutus litar, dasar cubaan semula dan papan pemuka semuanya membaca status HTTP untuk menentukan sama ada untuk cache, cuba semula atau memberi amaran. Dengan 200 di mana-mana, mereka menganggap kegagalan sebagai kejayaan, dan setiap amaran memerlukan penghuraian tersuai kod perniagaan.

Patutkah titik akhir senarai membawa metadata penomboran halaman?

Ya. Tanpa total atau kursor tiada penomboran, dan senarai kosong mesti mengembalikan [] dan bukannya null, jika tidak panggilan .map pada frontend rosak.

Bacaan lanjut

• null atau tinggalkan medan
• Format apa untuk cap masa