Format JSON REST API: Struktur Data, Aturan, dan Contoh

Format JSON (JavaScript Object Notation) adalah standar baku pertukaran data yang paling banyak digunakan dalam arsitektur REST API modern. Format ini berbasis teks ringan, mudah dibaca dan ditulis oleh manusia, serta mudah diterjemahkan dan diurai (parsed) oleh mesin.

Dalam ekosistem REST API, JSON berfungsi sebagai jembatan komunikasi antara klien (seperti aplikasi web atau mobile) dan server. Saat klien mengirimkan permintaan (request) atau menerima tanggapan (response), payload data umumnya dikemas dalam struktur JSON dengan header konten bertuliskan application/json.

Struktur Dasar dan Aturan Sintaks JSON

JSON dibangun atas dua struktur universal:

• Koleksi pasangan nama/nilai (Object): Di dalam bahasa pemrograman, ini dikenal sebagai objek, record, struct, dictionary, hash table, keyed list, atau associative array. Ditandai dengan kurung kurawal buka { dan tutup }.
• Daftar terurut nilai (Array): Di sebagian besar bahasa, ini dipahami sebagai larik, vektor, daftar (list), atau urutan (sequence). Ditandai dengan kurung siku buka [ dan tutup ].

Aturan mutlak yang wajib dipatuhi dalam penulisan sintaks JSON untuk REST API meliputi:

• Nama properti (key) wajib diapit menggunakan tanda kutip ganda ("). Kutip tunggal tidak diperbolehkan.
• Nilai (value) dapat berupa string (dengan kutip ganda), angka (integer/float), boolean (true/false), array, objek, atau nilai null.
• Setiap pasangan key-value dipisahkan oleh titik dua (:), dan antar-pasangan dipisahkan oleh koma (,).
• Koma terakhir (trailing comma) setelah elemen terakhir dalam objek atau array akan menyebabkan error parsing.

Tabel Komparasi Tipe Data JSON

Contoh Respon REST API yang Ideal

Berikut adalah contoh nyata struktur JSON untuk respon REST API pada endpoint data pengguna, yang mencakup data tunggal, array, penomoran halaman (pagination), dan metadata status:

{
  "status": "success",
  "code": 200,
  "message": "Data pengguna berhasil dimuat",
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total_data": 45
  },
  "data": [
    {
      "id": 1,
      "nama": "Dewi Lestari",
      "email": "[email protected]",
      "roles": ["admin", "editor"],
      "profil": {
        "telepon": "+6281234567890",
        "kota": "Bandung"
      },
      "terverifikasi": true,
      "tanggal_dibuat": "2026-01-15T08:30:00Z"
    },
    {
      "id": 2,
      "nama": "Ahmad Fauzi",
      "email": "[email protected]",
      "roles": ["user"],
      "profil": {
        "telepon": null,
        "kota": "Surabaya"
      },
      "terverifikasi": false,
      "tanggal_dibuat": "2026-02-10T14:15:00Z"
    }
  ]
}

Praktik Terbaik (Best Practices) Desain JSON API

Untuk memastikan API yang Anda bangun mudah dikonsumsi oleh pengembang lain, terapkan prinsip-prinsip berikut:

• Gunakan camelCase atau snake_case secara konsisten: Pilih salah satu konvensi penamaan key (misalnya tanggalLahir atau tanggal_lahir) dan gunakan secara konsisten di seluruh endpoint.
• Hindari Struktur Terlalu Dalam (Deep Nesting): Objek bersarang yang terlalu dalam (lebih dari 3 level) membuat kode klien sulit dibaca dan rentan terhadap error pembacaan properti null.
• Sediakan Wrapper Standar: Sertakan informasi status kode HTTP, pesan error/sukses, dan data utama di dalam root object agar klien dapat langsung mendiagnosis hasil permintaan.

Troubleshooting Error JSON Umum

Jika server API Anda mengembalikan error JSON Syntax Error atau gagal diurai oleh klien, periksa beberapa hal berikut:

1. Trailing Comma: Pastikan tidak ada koma di elemen terakhir dalam array atau objek.
2. Kutip Tunggal: Ganti seluruh tanda kutip tunggal (') pada key atau nilai string menjadi kutip ganda (").
3. Escape Karakter Khusus: Karakter seperti tanda kutip atau backslash di dalam string wajib di-escape menggunakan backslash (contoh: \").