Struktur apa yang sebaiknya dipakai response API

Intinya: nyatakan hasil dengan kode status 4xx/5xx, bawa payload dalam { "data": ..., "meta": ... }, dan beralih ke envelope error saat gagal; itu cukup untuk API internal, dan hanya platform publik dengan banyak integrator yang membutuhkan JSON:API atau OpenAPI.

Singkirkan dulu opsi terburuk: selalu mengembalikan 200 dengan hasil di field code.

Tiga bentuk

A. Objek telanjang

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

Bersih, dan semantik HTTP yang bekerja (404 tetap 404). Tetapi begitu Anda butuh pagination, warning atau trace id, tidak ada tempat untuk menaruhnya tanpa mengubah kontrak.

B. Envelope stabil

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

Payload dan metadata hidup terpisah, sehingga metadata baru tidak pernah mengubah bentuk data. Biayanya satu tingkat pembenahan bersarang.

C. Envelope untuk segalanya (hindari)

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

Bentuknya bukan dosa; praktiknya yang dosa. Status 200 untuk setiap hasil berarti CDN, gateway, circuit breaker, kebijakan retry dan dashboard semuanya melihat sukses. Setiap alert kemudian butuh parsing khusus.

Rekomendasi

Status HTTP untuk hasil, envelope untuk payload.

复制{
  "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 dapat dibaca mesin; message untuk manusia; details untuk error form tingkat field.

Aturan keras

1. Endpoint daftar wajib membawa metadata pagination. Tanpa total atau cursor tidak ada pager.
2. Daftar kosong mengembalikan [], jangan pernah null. null.map adalah gangguan yang berulang.
3. Timestamp dalam ISO 8601 dengan offset. Lihat format apa untuk timestamp.
4. Satu konvensi penamaan. snake_case atau camelCase, dikonversi sekali di batas.
5. Uang sebagai satuan minor integer atau string. 99.99 tidak eksak dalam floating point biner.
6. Jangan mencampuradukkan null dengan field yang tidak ada. Lihat null atau hilangkan field.

Kapan mengadopsi spesifikasi

• Platform publik dengan banyak integrator: JSON:API atau OpenAPI plus envelope bersama
• API internal satu tim: envelope di atas sudah cukup
• Kontrak kuat: Schema dulu, struktur dihasilkan darinya

Spesifikasi menghemat diskusi dan biaya onboarding. Untuk tim berlima, JSON:API biasanya adalah kerja yang merugikan.

FAQ

Bagaimana saya harus memilih antara objek telanjang dan envelope?

Gunakan envelope saat butuh pagination, warning atau requestId, sehingga meta bisa tumbuh tanpa mengubah bentuk data. Kembalikan objek telanjang hanya jika tidak butuh metadata dan bisa menerima bahwa menambahkan field nanti mengubah kontrak.

Mengapa API tidak boleh mengembalikan 200 untuk setiap hasil?

CDN, gateway, circuit breaker, kebijakan retry dan dashboard semuanya membaca status HTTP untuk memutuskan apakah harus cache, retry atau alert. Dengan 200 di mana-mana mereka memperlakukan kegagalan sebagai sukses, dan setiap alert butuh parsing khusus atas kode bisnis.

Haruskah endpoint daftar membawa metadata pagination?

Ya. Tanpa total atau cursor tidak ada pager, dan daftar kosong harus mengembalikan [] alih-alih null, atau panggilan .map di frontend rusak.

Bacaan lanjutan

• null atau hilangkan field
• Format apa untuk timestamp