Struktur JSON Tingkat Lanjut dan Pola Desain

Struktur Bersarang vs Datar

Pendekatan Seimbang (Direkomendasikan)

{
  "id": 1,
  "name": "John",
  "address": {
    "street": "123 Main St",
    "city": "NYC"
  },
  "contact": {
    "email": "john@example.com",
    "phone": "+1234567890"
  }
}

Hindari nesting berlebihan (>3-4 tingkat).

Normalisasi

Denormalisasi (Tertanam)

{
  "orders": [
    {
      "id": 1,
      "customer": {
        "id": 101,
        "name": "Alice"
      }
    }
  ]
}

Gunakan saat data sering dibaca, jarang diperbarui.

Dinormalisasi (Referensi)

{
  "orders": [
    { "id": 1, "customerId": 101 }
  ],
  "customers": {
    "101": { "id": 101, "name": "Alice" }
  }
}

Gunakan saat data sering berubah.

Pola Respons API

Pola Amplop (Envelope)

{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1
  }
}

Respons Kesalahan

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input tidak valid",
    "details": [
      {
        "field": "email",
        "message": "Format tidak valid"
      }
    ]
  }
}

Pola Paginasi

Berbasis Offset

{
  "data": [...],
  "pagination": {
    "page": 2,
    "perPage": 20,
    "total": 156
  }
}

Berbasis Kursor

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTAwfQ==",
    "hasMore": true
  }
}

Data Polimorfik

Pola Diskriminator

{
  "notifications": [
    {
      "type": "email",
      "recipient": "user@example.com",
      "subject": "Halo"
    },
    {
      "type": "sms",
      "phoneNumber": "+1234567890",
      "message": "Kode Anda adalah 123456"
    }
  ]
}

Versi (Versioning)

{
  "version": "2.0",
  "data": {
    "id": 1,
    "fullName": "John Doe"
  }
}

Pola Event/Pesan

{
  "eventId": "evt_abc123",
  "eventType": "user.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0",
  "data": {
    "userId": 123
  }
}

Praktik Terbaik

Konvensi Penamaan

{
  "userId": 1,       // camelCase (JavaScript)
  "user_id": 1       // snake_case (Python)
}

Bersikaplah konsisten!

Tanggal/Waktu

{
  "createdAt": "2024-01-15T10:30:00Z"  // ISO 8601
}

Uang/Mata Uang

{
  "price": {
    "amount": 2999,    // Sen
    "currency": "USD"
  }
}

Pola HATEOAS

{
  "id": 1,
  "name": "Product",
  "links": {
    "self": "/api/products/1",
    "update": "/api/products/1",
    "delete": "/api/products/1"
  }
}

Operasi Massal (Bulk)

{
  "operations": [
    { "op": "create", "data": {...} },
    { "op": "update", "id": 1, "data": {...} },
    { "op": "delete", "id": 2 }
  ]
}

Fieldset Jarang (Sparse Fieldsets)

GET /api/users?fields=id,name,email

{
  "data": [
    { "id": 1, "name": "Alice", "email": "alice@example.com" }
  ]
}

Kesimpulan

Desain struktur JSON yang baik:

Seimbangkan nesting secara tepat

Normalisasi berdasarkan pola baca/tulis

Gunakan pola yang konsisten

Beri versi pada data Anda

Ikuti konvensi penamaan

JSON yang terstruktur dengan baik membuat API lebih mudah digunakan dan dipelihara!