Pada umumnya standarisasi JSON REST API RESPONSE memang tidak ditentukan, namun untuk pencapaian efisiensi, konsistensi dan kemudahan maka dibutuhkan standarisasi tersebut.
Pencapaian ini kami temukan dan terapkan setelah mengerjakan banyak proyek degan kasus-kasus yang umum, sehingga kami simpulkan menjadi suatu standarisasi yang kami gunakan sampai sekarang.
Kami yakin bagi anda yang menemukan artikel ini, berarti Anda sudah mengerti akan segalah hal tentang JSON REST API RESPONSE, sehingga kami tidak menjelaskan detail tentang hal-hal kecil yang berhubungan tentang itu.
Goal kami untuk adalah efisiensi, konsistensi dan kemudahan
Metode dan Pola yang kami gunakan adalah selalu menggunakan fitur yang sudah ada dan umum, seperti
- HTTP Response Code (Wiki)
- Patterns for API Design (Microservice Api Patterns)
kami hanya fokus pada RESPONSE DESIGN tidak pada metode dan pola REQUEST.
Berikut ini standarisasi HTTP Response Code yang kami gunakan:
| CODE | DETAIL | GROUP |
|---|---|---|
| 200 | sukses untuk semua aksi baik Request client, Proses pada server (Backend) dan Response yang dikembalikan | success |
| 400 | error karena validasi request paramater atau payload tidak sesuai | error |
| 401 | error karena tidak memiliki otorisasi | error |
| 403 | error karena tidak memiliki akses | error |
| 404 | error karena data/service tidak ditemukan | error |
| 500 | error pada sisi server, pada response ini selalu mengirimkan kode referensi error pada key error_ref. Kode referensi tersebut nanti akan digunakan Backend Developer untuk mencari error pada server logs |
error |
Design respon JSON yang kami gunakan hanya memiliki 2 key utama yaitu:
| Deskripsi | Keys | Detail |
|---|---|---|
| Status Respon | success, error |
- semua respon dengan kode 200 maka akan memiliki key success - semua respon dengan kode selain 200 maka akan memiliki key error |
| Data Respon | data |
key ini bebas digunakan untuk memuat data yang diinginkan baik ketika status respon sukses atau pun error Khusus error kode 500 akan terdapat key error_ref di dalam key data |
Berikut ini adalah contoh penggunaannya:
Success Response
{
"success": "Success Messages ...",
"data": [...]
}
Error Response
{
"error": "Error Messages ...",
"data": [...]
}
Error Response 500
{
"error": "Error Messages ...",
"data": [
"error_ref": "XSADC",
...
]
}
Karena prinsip kami yang mengutamakan kesederhanaan demi tercapai kemudahan dalam pengelolaan HTTP respon REST API baik dari sisi Backend maupun Frontend, semua kode tersebut merupakan kode yang selama ini kami temui dan paling sering digunakan dan memiliki relevansi kuat dengan kebutuhan integerasi yang umum.
Karena berdasarkan pengalaman kami, apapun aksi yang sukses semua bisa dirangkum dalam kode 200 karena dari sisi client tidak membutuhkan informasi jenis sukses apa yang mereka terima.
Karena semakin sedikit main keys akan semakin mudah untuk developer dalam mendefiniskan keperluan dan implementasi penggunaan desain kode pemogramman.
Selain itu client hanya fokus pada success dan error respon dimana keterangan nya sudah terdapat pada value masing masing keys sehingga tidak dibutuhkan key lain untuk menjelaskan kenapa success atau error itu terjadi dan untuk key data merupakan detail dari status tersebut, pola ini sangat baik untuk konsistensi data dan efisiensi bandwith.
Dari sisi developer hal ini memudahkan untuk membaca status sukses atau error ketika response didefinisikan atau didapat, hal ini akan dijelaskan pada bagian selanjutnya.
Karena seluruh error telah umum didefinisikan pada HTTP Response Code kecuali kode error 500
Error kode 500 hanya menginformasikan terjadi error pada server, oleh karena itu server/backend hanya perlu mengirimkan kode referensi error berupa minimal 5 string karakter kapital yang nanti kode tersebut akan digunakan untuk mencari detail error pada error logs
Kenapa tidak menggunakan angka? karena kita tidak perlu mendefinisikan error itu sendiri. Hal ini tidak baik untuk pengembangan, karena akan ada pendefinisian kode baru untuk error baru.
Developer Backend hanya perlu membuat engine yang menempelkan kode referensi pada setiap error log yang dihasilkan, hal ini sangat baik dari sisi keamanan dan kemudahan informasi dari sisi client, karena client tidak perlu tahu detail error yang terjadi dari sisi server/Backend.
Kenapa harus didalam main key data ? karena disitulah detail dari status yang terjadi.
| ❌ We Don't do this |
|---|
Kami tidak menggunakan Metode dan Pola Design Response yang bisanya menyertakan key message,error_message dan sejenisnya karena ini akan boros bandwith dan tidak konsisten pada struktur design |
Umumnya pada Metode dan Pola Design Response yang lain mereka mendefinisikan kode error khusus berupa angka, yang kemudian dikirim kepada client berupa key tersendiri misalnya error_code, error_number dan sejenisnya, hal ini tidak efisien, tidak aman dan tidak muda untuk dikelola |
Semoga bermanfaat.