API response contract

[YogiPristiawan]

Should we create an API response contract in every response, like

{
    message: "something",
    data: {
        id: "123",
        name: "foo",
    }
}

[aldy505]

Nggak. Kalo mau bikin gitu, isi "message" harus konsisten. Isi "data" juga keliatannya dynamic. We're trying to avoid that.

Lagian kalo ada error, seharusnya hal pertama yang di cek itu HTTP status code, bukan response body.

Kalo dari sisi frontend, pas fetch ya jadi aneh: responseBody.data.data, dan dia harus yakin sama schemanya. Frontend kita strong typed language semua soalnya (Typescript dan Dart), jadi jangan di enforce buat response body yang bisa anything di dalem "data". Lebih baik declare specific aja, lebih simpel, lebih jelas.

[yus-ham]

Usul saya gini aja:

Pakai HTTP response code.
Body dibedakan berdasarkan jenis request: GET one object, GET collection, POST, PATCH, DELETE

// GET object, code: 200 OK, 404 object not found
// POST object code: 201 Created
{
    id: 1,
    prop1: "value1",
    prop2: "value2"
}

// GET  object collection, code 200 OK
// Additionally pagination metadata in headers including :
// paging-total, paging-current-page, paging-per-page, paging-page-count
[
    object1,
    object2,
    ...
] 

// DELETE object, code 204 no content, 404 object not found

// PATCH object, code 200 OK, 204 if no content provided, 404 object not found

// validation fails, code: 422 Unprocessable
{
    field1:  ["message1", "message2"],
    field2:  ["message1", "message2"],
}

// server error, code 500
// body may contains stack trace information only for debugging

mungkin ada yang kurang sih, tapi saya lupa