Blog

JSON Patch: Cara Cerdas Memperbarui Data API Anda

INEZA Felin-Michel

INEZA Felin-Michel

1 September 2025

JSON Patch: Cara Cerdas Memperbarui Data API Anda

Apidog untuk Perusahaan

Penerapan On-Premises

SSO & RBAC

Sesuai SOC 2

Jelajahi Apidog Enterprise

Anda telah membangun API modern. Metode GET mengambil data, metode POST membuat sumber daya baru—sejauh ini lancar. Namun ketika menyangkut pembaruan data, hal-hal menjadi rumit.

Misalnya, seorang pengguna hanya ingin mengubah emailnya. Apakah Anda benar-benar perlu mereka mengirim ulang *seluruh* profil pengguna? Itu canggung, tidak efisien, dan rawan kesalahan—terutama dengan koneksi yang lambat atau pembaruan yang saling bertentangan.

Ada cara yang lebih baik: JSON Patch.
Alih-alih mengirim seluruh objek, Anda hanya mengirimkan perubahannya. Bayangkan seperti memberikan daftar perubahan kepada penjahit daripada membuat ulang seluruh jas.

Karena JSON telah menjadi bahasa universal untuk API, JSON Patch menawarkan solusi ringan dan elegan untuk pembaruan parsial.

Tentu saja, merancang dan menguji API dengan JSON Patch membutuhkan alat yang tepat. Di sinilah Apidog berperan. Ini memungkinkan Anda membuat, menguji, dan memvalidasi permintaan JSON Patch dengan mudah—sehingga Anda tahu pembaruan Anda berfungsi sesuai yang diinginkan sebelum menulis satu baris kode pun. Yang terbaik, ini gratis untuk diunduh dan mulai bereksperimen hari ini.

💡
Ingin alat Pengujian API yang hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terintegrasi, All-in-One untuk Tim Pengembang Anda agar bekerja bersama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!

tombol

Selanjutnya, mari kita uraikan apa itu JSON Patch, bagaimana cara kerjanya, dan mengapa itu harus menjadi bagian dari proyek Anda berikutnya.

Masalah: Permintaan PUT "Buta"

Untuk memahami mengapa JSON Patch sangat berguna, kita perlu memahami masalah yang dipecahkannya terlebih dahulu. Secara tradisional, pembaruan sumber daya dalam API RESTful dilakukan dengan metode HTTP **`PUT`**.

Permintaan **`PUT`** dimaksudkan untuk menjadi idempoten (melakukan permintaan yang sama berkali-kali memiliki efek yang sama dengan melakukannya sekali) dan biasanya menggantikan *seluruh* sumber daya di URL target dengan representasi baru yang disediakan dalam *body* permintaan.

Mari kita bayangkan sumber daya profil pengguna:

GET /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.old@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Sekarang, jika John hanya ingin mengubah alamat emailnya, permintaan **`PUT`** yang khas akan terlihat seperti ini:

PUT /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.new@example.com", // Bidang yang diubah
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Apakah Anda melihat masalahnya? Kita harus mengirim kembali setiap bidang, meskipun 99% data tidak berubah. Pendekatan ini memiliki beberapa kelemahan:

  1. Peningkatan Bandwidth: Kita mengirim banyak data yang tidak perlu melalui jaringan. Untuk sumber daya besar, ini bisa menjadi penurunan kinerja yang signifikan, terutama pada jaringan seluler.
  2. Risiko Konflik yang Lebih Tinggi: Jika proses lain memperbarui bidang **`age`** saat John mengedit **`email`**-nya, permintaan **`PUT`** John dapat secara tidak sengaja menimpa usia baru itu dengan nilai lama yang dia kirim.
  3. Kompleksitas bagi Klien: Aplikasi klien harus terlebih dahulu **`GET`** seluruh sumber daya, memodifikasi bidang tertentu, dan kemudian **`PUT`** seluruhnya kembali. Ini adalah beberapa langkah dan mengharuskan klien untuk mengelola seluruh status.

Di sinilah metode HTTP **`PATCH`** datang untuk menyelamatkan.

Solusi: Memperkenalkan HTTP PATCH dan JSON Patch

Metode HTTP **`PATCH`** diperkenalkan untuk memungkinkan modifikasi parsial pada suatu sumber daya. Tidak seperti **`PUT`**, yang menggantikan seluruh sumber daya, **`PATCH`** menerapkan serangkaian *perubahan* pada sumber daya.

Namun ada kendala: standar HTTP tidak mendefinisikan seperti apa format "perubahan" tersebut. Anda bisa menciptakan sendiri. Anda bisa mengirimkan sesuatu seperti:

{ "op": "change_email", "value": "new@example.com" }

Namun ini akan menjadi kustom, non-standar, dan pengembang lain harus mempelajari bahasa spesifik Anda.

Inilah celah yang diisi oleh JSON Patch. JSON Patch (didefinisikan dalam RFC 6902) adalah format standar untuk menentukan perubahan yang akan diterapkan pada dokumen JSON. Ini menyediakan bahasa yang jelas dan tidak ambigu untuk menggambarkan dengan tepat bagaimana dokumen JSON harus dimodifikasi.

Ketika Anda menggabungkan metode HTTP **`PATCH`** dengan *body* yang diformat sebagai dokumen JSON Patch, Anda memiliki cara yang ampuh dan berbasis standar untuk melakukan pembaruan parsial.

Bagaimana JSON Patch Bekerja: Dasar-dasar

Dokumen JSON Patch selalu berupa array JSON. Setiap elemen dalam array adalah objek operasi. Operasi-operasi ini diterapkan pada dokumen target secara berurutan, dan seluruh *patch* bersifat atomik, artinya jika ada satu operasi yang gagal, seluruh *patch* dibatalkan, dan dokumen dibiarkan tidak berubah.

Setiap objek operasi memiliki anggota **`op`** (singkatan dari "operation") wajib yang menentukan tindakan yang akan dilakukan. Operasi yang paling umum adalah **`add`**, **`remove`**, **`replace`**, **`move`**, dan **`copy`**.

Mari kita lihat contoh sebelumnya tentang John yang mengubah emailnya. Menggunakan JSON Patch, permintaannya menjadi jauh lebih sederhana:

PATCH /users/123

[
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

Itu saja! Kita mengirimkan satu operasi: "ganti nilai di jalur '/email' dengan nilai baru ini." Permintaannya kecil, jelas, dan didorong oleh tujuan. Kita tidak menyentuh bidang lain.

Memahami Properti path

Properti **`path`** adalah JSON Pointer (RFC 6901), sebuah string yang menggunakan sintaks berbasis garis miring untuk menavigasi dokumen JSON ke nilai spesifik yang ingin Anda manipulasi.

Sintaks ini ampuh untuk menavigasi struktur JSON bersarang.

JSON Patch vs JSON Merge Patch

Pengembang sering kali bingung antara JSON Patch (RFC 6902) dengan JSON Merge Patch (RFC 7386). Mari kita jelaskan.

JSON Patch:

JSON Merge Patch:

Singkatnya:

Operasi JSON Patch

Mari kita uraikan operasi yang paling umum dengan contoh. Kita akan menggunakan profil pengguna yang sama sebagai dokumen target kita.

1. Operasi add

Operasi **`add`** digunakan untuk menyisipkan nilai baru ke dalam objek atau array.

Menambahkan properti baru ke objek:

{ "op": "add", "path": "/twitterHandle", "value": "@johndoe" }

Ini menambahkan bidang **`twitterHandle`** baru ke objek pengguna.

Menambahkan elemen ke array (pada indeks tertentu):

Bayangkan pengguna memiliki array **`"hobbies"`**: **`["reading", "cycling"]`**.

{ "op": "add", "path": "/hobbies/1", "value": "hiking" }

Ini menyisipkan "hiking" pada indeks 1, menghasilkan **`["reading", "hiking", "cycling"]`**. Untuk menambahkan ke akhir array, Anda dapat menggunakan **`/-`**: **`{ "op": "add", "path": "/hobbies/-", "value": "hiking" }`**.

2. Operasi remove

Operasi **`remove`** menghapus nilai pada lokasi yang ditentukan.

Menghapus properti dari objek:

{ "op": "remove", "path": "/age" }

Ini menghapus seluruh bidang **`age`** dari objek pengguna.

Menghapus elemen dari array:

{ "op": "remove", "path": "/hobbies/0" }

Ini menghapus elemen pertama (indeks 0) dari array **`hobbies`**.

3. Operasi replace

Operasi **`replace`** pada dasarnya adalah kombinasi dari **`remove`** dan **`add`** pada jalur yang sama. Ini menggantikan nilai yang ada di suatu lokasi dengan nilai baru. Contoh email kita adalah **`replace`** klasik.

Mengubah preferensi tema pengguna:

{ "op": "replace", "path": "/preferences/theme", "value": "dark" }

4. Operasi move

Operasi **`move`** menghapus nilai dari satu lokasi dan menambahkannya ke lokasi lain.

Memindahkan nilai dari satu properti ke properti lain:

{ "op": "move", "from": "/firstName", "path": "/first_name" }

Ini akan memindahkan nilai **`firstName`** ke properti baru bernama **`first_name`** dan menghapus properti **`firstName`** yang lama.

5. Operasi copy

Operasi **`copy`** menyalin nilai dari satu lokasi ke lokasi lain. Nilai aslinya tetap tidak berubah.

Membuat cadangan pengaturan:

{ "op": "copy", "from": "/preferences/theme", "path": "/backupTheme" }

Ini menyalin nilai tema saat ini ke bidang **`backupTheme`** yang baru.

6. Operasi test

Ini adalah fitur keamanan. Operasi **`test`** memeriksa bahwa nilai di suatu lokasi sama dengan nilai yang ditentukan. Jika tes gagal, seluruh *patch* dibatalkan. Ini sangat berguna untuk mencegah konflik (penguncian optimistik).

Memastikan tidak ada orang lain yang mengubah email sebelum memperbaruinya:

[
  { "op": "test", "path": "/email", "value": "john.old@example.com" },
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

Jika **`email`** saat ini *bukan* **`"john.old@example.com"`** (mungkin proses lain sudah mengubahnya), operasi **`test`** gagal, dan **`replace`** tidak pernah terjadi. Ini memastikan pembaruan Anda didasarkan pada status terbaru yang diketahui.

Mengapa Menggunakan JSON Patch? Manfaatnya

  1. Efisiensi: Manfaat yang paling jelas. Anda hanya mengirimkan perubahannya, secara signifikan mengurangi ukuran *payload* dan meningkatkan kinerja.
  2. Kontrol Konkurensi: Operasi **`test`** menyediakan mekanisme bawaan untuk *optimistic locking*, membantu Anda menghindari pembaruan yang hilang dan *race conditions*.
  3. Atomisitas: Sifat semua-atau-tidak-sama sekali dari aplikasi *patch* memastikan data Anda tetap konsisten. Jika operasi kelima dalam *patch* sepuluh operasi gagal, empat operasi pertama akan di-*rollback*.
  4. Kejelasan dan Niat: *Body* permintaan dengan jelas menggambarkan *niat* perubahan ("ganti email", "tambah hobi") daripada hanya membuang status baru. Ini membuat *log* lebih mudah dibaca dan *debugging* lebih mudah.
  5. Standardisasi: Ini adalah standar IETF (RFC 6902). Pengembang lain akan mengenalinya, dan banyak pustaka serta *framework* di berbagai bahasa pemrograman memiliki dukungan bawaan untuk mengurai dan menerapkan dokumen JSON Patch.

Jebakan dan Kesalahan Umum dengan JSON Patch

Meskipun JSON Patch sangat ampuh, pengembang sering kali mengalami masalah ini:

Mengapa API Menggunakan JSON Patch

API menyukai JSON Patch karena:

Misalnya, API GitHub mendukung JSON Patch untuk mengedit metadata repositori secara efisien.

JSON Patch dalam REST API

Dalam RESTful API, JSON Patch sering digunakan dengan metode HTTP PATCH.

PATCH vs PUT:

Dengan JSON Patch, `Content-Type` adalah:

application/json-patch+json

Ini memberi tahu server bahwa *body* berisi dokumen JSON Patch.

JSON Patch dalam GraphQL dan Protokol Lainnya

Meskipun JSON Patch terutama digunakan dalam REST API, ia juga relevan dalam:

Bagaimana JSON Patch Meningkatkan Efisiensi

Bayangkan aplikasi seluler yang menyinkronkan profil pengguna. Alih-alih mengunggah ulang file JSON 2MB untuk setiap pembaruan kecil, aplikasi dapat mengirimkan permintaan *patch* kecil.

Ini berarti:

Tantangan dan Pertimbangan

JSON Patch sangat ampuh, tetapi bukan tanpa kerumitan.

  1. Implementasi Kompleks di Sisi Server: Menerapkan *patch* dengan benar di server lebih kompleks daripada sekadar menerima objek JSON baru. Anda perlu memvalidasi setiap operasi, menangani *pointer* ke jalur yang tidak ada dengan tepat, dan memastikan seluruh urutan diterapkan secara atomik. Untungnya, sebagian besar *framework* web modern memiliki pustaka untuk menangani ini untuk Anda (misalnya, **`json-patch`** untuk Node.js, **`jsonpatch`** untuk Python, **`JsonPatchDocument`** di .NET).
  2. Potensi Kesalahan: Dokumen *patch* yang salah format atau *pointer* yang tidak valid (misalnya, mencoba **`replace`** bidang yang tidak ada) akan menghasilkan kesalahan. API Anda harus menanganinya dengan baik dan mengembalikan pesan kesalahan yang jelas (biasanya **`422 Unprocessable Entity`** atau **`400 Bad Request`**).
  3. Bukan Solusi Ajaib: Untuk sumber daya yang sangat sederhana, **`PUT`** mungkin masih lebih sederhana. JSON Patch bersinar ketika sumber daya Anda besar atau ketika Anda perlu mendukung pembaruan yang kompleks dan kondisional.

Menguji Endpoint JSON Patch dengan Apidog

Menguji JSON Patch secara manual bisa membuat frustrasi. Di sinilah alat API yang canggih menjadi sangat berharga. **Apidog**, platform pengembangan API all-in-one, bisa menjadi penyelamat besar di sini:

tombol

Contoh alur kerja di Apidog:

  1. Buat permintaan baru.
  2. Atur metode ke PATCH.
  3. Tambahkan Content-Type: application/json-patch+json.
  4. Masukkan array JSON Patch Anda.
  5. Kirim dan verifikasi hasilnya secara instan.

Dengan menggunakan Apidog, Anda beralih dari menebak apakah *patch* Anda benar menjadi mengetahui bahwa itu dibangun dengan benar, memungkinkan Anda untuk dengan percaya diri mengimplementasikan dan mengonsumsi API JSON Patch dan mulai menguji JSON Patch seperti seorang profesional.

Praktik Terbaik JSON Patch

Untuk menggunakan JSON Patch secara efektif:

  1. Validasi dokumen JSON Patch Anda sebelum mengirim.
  2. Gunakan operasi *test* saat konsistensi penting.
  3. Jaga *patch* tetap kecil untuk efisiensi.
  4. Dokumentasikan API Anda dengan jelas saat menggunakan JSON Patch.
  5. Gunakan alat seperti Apidog untuk menyederhanakan pengujian.

Kesimpulan: Merangkul Standar API yang Lebih Efisien

Jadi, apa itu **JSON Patch**?

Ini adalah cara standar untuk menjelaskan **perubahan pada dokumen JSON** menggunakan operasi seperti tambah, hapus, dan ganti. Alih-alih mengirim objek lengkap, Anda dapat mengirimkan hanya perubahannya membuat API Anda lebih **efisien, andal, dan fleksibel**.

JSON Patch mengubah cara kita berpikir tentang memperbarui data melalui API. Ini mengalihkan kita dari instrumen tumpul penggantian dokumen penuh ke presisi perubahan bedah. Dengan merangkul standar ini, kita membangun API yang lebih efisien, lebih kecil kemungkinannya mengalami konflik, dan lebih jelas dalam tujuannya.

Meskipun membutuhkan sedikit lebih banyak pemikiran awal di sisi server, manfaat bagi aplikasi klien dan kinerja jaringan sangat besar. Lain kali Anda mendesain *endpoint* pembaruan, tahan diri dari **`PUT`** bawaan dan tanyakan pada diri Anda: "Bisakah ini menjadi pekerjaan untuk **`PATCH`**?"

Bagi pengembang, memahami JSON Patch adalah kunci untuk bekerja dengan API modern, terutama saat menangani pembaruan parsial. Dan dengan alat seperti **Apidog**, Anda dapat menguji, memvalidasi, dan *debug* permintaan JSON Patch dengan mudah.

tombol

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Daftar gratisUnduh