Panduan Lengkap Desain JSON API: Prinsip, Praktik Terbaik & Standar Skema

Artikel ini menyediakan panduan komprehensif tentang desain JSON yang terstruktur, mencakup prinsip, praktik terbaik, dan standar skema, serta menunjukkan bagaimana pemodelan skema EchoAPI dapat membantu mencapai desain data terstruktur yang standar, otomatis, dan cerdas.

Dalam arsitektur perangkat lunak API-first saat ini, JSON telah menjadi salah satu format pertukaran data yang paling banyak digunakan. Baik itu API RESTful, file konfigurasi, penyimpanan basis data, atau analisis log, JSON memainkan peran yang sangat mendasar.

Namun, melalui praktik sistem nyata yang luas, kami mengamati bahwa desain JSON yang kacau, kurangnya standarisasi, dan antarmuka yang tidak konsisten masih sangat umum terjadi. Masalah ini sangat memengaruhi kemampuan pemeliharaan sistem, efisiensi kolaborasi front-end/back-end, serta kemampuan pengembangan API di masa depan.

Artikel ini secara sistematis menguraikan pengetahuan inti tentang desain JSON terstruktur, menganalisis masalah umum secara mendalam, dan memperkenalkan cara memanfaatkan kemampuan pemodelan Schema EchoAPI untuk mencapai desain struktur data yang terstandarisasi, otomatis, dan cerdas.

Sistem Pengetahuan Inti Desain JSON Terstruktur

1.1 Struktur Dasar dan Tipe Data

JSON terdiri dari dua struktur dasar:

Tipe Contoh Deskripsi
Object { "key": "value" } Pasangan kunci-nilai tak berurutan
Array [1, 2, 3] Kumpulan berurutan

Tipe data yang didukung meliputi:

  • String: "hello"
  • Number: 42, 3.14
  • Boolean: true, false
  • Null: null
  • Object
  • Array

1.2 Pola Struktur JSON Umum

Struktur Datar (Flat)

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}
  • βœ… Sederhana dan ideal untuk objek dasar
  • ❗ Tidak dapat menggambarkan semantik bisnis atau relasi kompleks

Struktur Bersarang (Nested)

{
  "user": {
    "id": 1,
    "profile": {
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}
  • βœ… Mencerminkan model objek dunia nyata
  • ❗ Hindari nesting berlebihan (struktur "boneka Rusia")

Array dari Objek

{
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ]
}
  • βœ… Umum untuk merepresentasikan daftar
  • ❗ Pastikan konsistensi struktur item dalam array

1.3 Prinsip Desain dan Masalah Umum

Konsistensi

Definisi: Gunakan nama field, tingkat hierarki, dan tipe data yang konsisten antar antarmuka.

❌ Contoh Salah:

// API A
{ "user_id": 101, "user_name": "Tom" }
// API B
{ "uid": 101, "name": "Tom" }

βœ… Contoh Benar:

{ "user_id": 101, "user_name": "Tom" }

Rekomendasi:

  • Tentukan standar nama domain (misal selalu user_id, bukan uid, id, atau userid)
  • Dokumentasikan konvensi penamaan

Keterbacaan

Definisi: Gunakan nama field yang bermakna dan jelas. Hindari singkatan atau istilah ambigu.

❌ Contoh Salah:

{ "u_n": "Alice", "t_c": "2025-07-09" }

βœ… Contoh Benar:

{ "user_name": "Alice", "created_time": "2025-07-09T12:00:00Z" }

Rekomendasi:

  • Gunakan kata lengkap (misal email bukan eml)
  • Pertahankan kejelasan dalam bahasa Inggris untuk kolaborasi dan dokumentasi
  • Adopsi kamus penamaan bersama (created_at, status, dll)

Ortogonalitas

Definisi: Setiap field harus memiliki tujuan tunggal dan jelas.

❌ Contoh Salah:

{ "user_info": "Tom,101,true" }

βœ… Contoh Benar:

{
  "user": {
    "id": 101,
    "name": "Tom",
    "is_active": true
  }
}

Rekomendasi:

  • Jangan gabungkan banyak nilai dalam satu field string
  • Gunakan struktur nested untuk mewakili entitas kompleks

Batasi Kedalaman Nesting

Definisi: Jaga nesting antara 2–3 level untuk keterbacaan dan performa.

❌ Contoh Salah:

{
  "user": {
    "profile": {
      "meta": {
        "settings": {
          "preferences": {
            "theme": "dark"
          }
        }
      }
    }
  }
}

βœ… Contoh Benar:

{
  "user": {
    "theme": "dark"
  }
}

Rekomendasi:

  • Batasi nesting ≀3 level
  • Gunakan referensi atau model terpisah untuk struktur kompleks

Ekstensibilitas

Definisi: Mudahkan penambahan field atau substruktur tanpa merusak desain lama.

❌ Struktur Datar Salah:

{
  "user_name": "Alice",
  "user_email": "alice@example.com",
  "user_age": 25
}

βœ… Struktur Bersarang Benar:

{
  "user": {
    "profile": {
      "name": "Alice",
      "email": "alice@example.com",
      "age": 25
    }
  }
}

Rekomendasi:

  • Gunakan modul nested (profile, settings, dll)
  • Rancang dengan pertimbangan pengembangan di masa depan

Minimalkan Redundansi

Definisi: Hindari duplikasi informasi yang tidak perlu.

❌ Contoh Salah:

{
  "user_id": 101,
  "user": {
    "id": 101,
    "name": "Alice"
  }
}

βœ… Contoh Benar:

{
  "user": {
    "id": 101,
    "name": "Alice"
  }
}

Rekomendasi:

  • Hapus field redundan (terutama ID dan status)
  • Buat payload ringkas dan jelas

Kejelasan Tipe

Definisi: Tipe data field harus konsisten di semua konteks.

❌ Contoh Salah:

{ "status": 1 }
{ "status": "active" }
{ "status": { "code": 1, "text": "active" } }

βœ… Contoh Benar:

{ "status": "active" }

atau

{ "status": { "code": 1, "label": "active" } }

Rekomendasi:

  • Gunakan tipe tetap (string, object, dll)
  • Pilih enum atau objek terstruktur untuk field status

Ringkasan

Prinsip Deskripsi
Konsistensi Penamaan field, struktur hierarki, dan format data harus konsisten antar API berbeda
Keterbacaan Nama field harus jelas dan mudah dipahami secara intuitif
Ortogonalitas Setiap field menyampaikan satu makna yang jelas; hindari penggabungan makna dalam satu field
Batasi Kedalaman Batasi kedalaman nesting JSON untuk keterbacaan, performa parsing, dan efisiensi front-end
Ekstensibilitas Struktur JSON harus dirancang agar mudah dikembangkan dan diperluas di masa depan
Minimalkan Redundansi Hindari field duplikat agar struktur data tetap bersih dan efisien
Kejelasan Tipe Pastikan tipe data field stabil dan konsisten; hindari pencampuran tipe dinamis

1.4 Standar Penamaan

Item Rekomendasi
Gaya Penamaan Gunakan snake_case (user_name) atau camelCase (userName)
Field ID Gunakan nama standar: id, user_id, order_id
Field Waktu Gunakan format ISO 8601: "2025-07-09T12:00:00Z"
Field Status Gunakan enum semantik seperti "active", hindari 1 / 0

Praktik Terbaik untuk Desain JSON

Kejelasan Tipe

❌ Salah:

{ "price": "123.45" }

βœ… Benar:

{ "price": 123.45 }

Rekomendasi:

  • Gunakan tipe number untuk bidang numerik
  • Gunakan string (misalnya format ISO 8601) untuk bidang waktu secara konsisten

Gunakan Enum atau Boolean untuk Status

❌ Salah:

{ "status": 1 }

βœ… Benar (Boolean):

{ "is_active": true }

βœ… Benar (Enum):

{ "status": "active" }

Format Respon Error Standar

❌ Salah:

{ "error_msg": "Invalid email", "code": 400 }

βœ… Benar:

{
  "code": 400,
  "message": "Invalid request parameter",
  "error": {
    "field": "email",
    "reason": "Invalid format"
  }
}

Gunakan JSON Schema untuk Definisi Struktur

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["email"]
}

Manfaat:

  • Batasan bidang yang jelas
  • Validasi otomatis untuk request/response
  • Mendukung dokumentasi dan alat pengujian

Hindari Penggunaan null Berlebihan

❌ Salah:

{ "nickname": null }

βœ… Lebih Baik:

{
  // cukup hilangkan "nickname" jika tidak disediakan
}

βœ… Gunakan null hanya saat diperlukan:

{ "nickname": null } // Menandakan secara eksplisit bahwa pengguna menghapus isi bidang

Ringkasan

Praktik Contoh yang Direkomendasikan
Kejelasan Tipe Gunakan price: number, bukan string seperti "123.45".
Gunakan Enum atau Boolean untuk Status Gunakan status: "active" atau is_active: true, bukan status: 1.
Format Error Standar Gunakan struktur error standar seperti { code, message, error }.
Definisikan Struktur dengan JSON Schema Tentukan dengan jelas tipe bidang, bidang yang wajib, batasan format, dan lain-lain.
Hindari Penggunaan null Berlebihan Hilangkan bidang tanpa nilai daripada mengembalikan "field": null, kecuali null memiliki makna semantis.

EchoAPI Schema: Pemodelan JSON Terpadu

Panduan Lengkap Desain JSON API: Prinsip, Praktik Terbaik & Standar Skema

1. Visual Schema Designer

  • Tambah atau edit field secara visual, atur tipe, deskripsi, dan status wajib
  • Drag-and-drop untuk mengurutkan field
  • Mendukung objek nested, array, dan referensi
  • Pratinjau instan schema dan contoh JSON
  • Kelola model reusable berdasarkan kategori untuk kemudahan pemeliharaan

2. Impor Berbagai File Struktur

Konversi mudah dari format data lama ke schema yang bisa dipakai:

  • βœ… Contoh JSON
  • βœ… JSON Schema
  • βœ… XML
  • βœ… MySQL DDL

Mempercepat pembuatan schema, sangat berguna untuk API/database legacy.

3. AI-Assisted Schema Completion

Fitur Deskripsi
Deskripsi Field Cerdas Label yang mudah dipahami otomatis
Inferensi Tipe & Contoh Saran tipe field, contoh nilai, default
Penyelesaian Referensi Reuse dan sinkron definisi model
Auto-Fill Aturan Schema Tambah otomatis required, enum, dll

Hemat waktu dan kurangi kesalahan manual.

4. Ekspor & Kompatibilitas Standar

EchoAPI mendukung interoperabilitas:

  • βœ… Ekspor ke OpenAPI 3.0
  • βœ… Dukungan live preview di Swagger Editor
  • βœ… Dukungan JSON Schema lanjutan (anyOf, oneOf, $ref)
  • βœ… Ekspor cepat: mock data, dokumentasi API, SDK

5. Meningkatkan Sinkronisasi Frontend–Backend

Schema terpadu menjaga ekspektasi konsisten antara developer front-end dan back-end.

6. Validasi dan Penegakan Struktur Data

Schema di EchoAPI menegakkan tipe data, aturan wajib, dan batasan nilai.

7. Tingkat Reuse dan Modularitas Tinggi

Pisahkan struktur bersama jadi schema mandiri yang bisa dipakai ulang di berbagai endpoint.

8. Kustomisasi Validasi Tingkat Field

Kontrol validasi seperti:

  • Batas panjang array
  • Min/max string length
  • Rentang angka
  • Set enum, pola, format

9. Pratinjau Langsung & Mode Kode

Beralih antara editor visual dan kode JSON Schema.

10. Integrasi Toolchain Multi-platform

Dukung plugin IntelliJ, VS Code, ekstensi Chrome tanpa login.

EchoAPI mempercepat desain schema dengan alat cerdas, editing visual, impor pintar, dan dukungan standar penuh β€” membuat workflow API Anda lebih cepat, konsisten, dan mudah dipelihara.

EchoAPI Documentation | EchoAPI
What Is a Schema in API Development? Uses, Benefits, and Best Practices with EchoAPI
This article delves into what schemas are, their significance in API design, and how tools like EchoAPI can streamline the implementation and management of schemas to enhance API development
Streamline Your API Design Workflow: Using Schemas with EchoAPI
Schemas are vital in API development, offering a structured way to define and validate data. They improve data integrity and streamline communication between services, ensuring consistency.

Pemikiran Akhir: Struktur adalah Kontrak, Schema adalah Bahasa

API adalah bahasa penghubung antar sistem, dan JSON adalah sintaksnya. Dengan EchoAPI, tim Anda bisa:

  • Meminimalkan risiko perubahan struktur
  • Menghindari miskomunikasi
  • Mempercepat kolaborasi front-end/back-end
  • Menjaga dokumentasi dan kode tetap sinkron
  • Membangun standar struktur data yang terpadu

Jika Anda merancang API kompleks atau menginginkan struktur JSON yang lebih kuat dan cerdas β€” EchoAPI Schema sangat layak dicoba.