PATCH

Penggunaan

Permintaan PATCH mengirimkan sekumpulan instruksi yang menjelaskan cara memodifikasi sumber daya yang sudah ada. Berbeda dengan PUT yang mengganti seluruh sumber daya, PATCH hanya mengubah field atau properti yang ditentukan.

Body permintaan berisi dokumen patch dalam format yang dipahami server. Header Content-Type mengidentifikasi format patch tersebut. Header Accept-Patch pada response server mengumumkan format patch yang didukung.

Catatan

PATCH tidak usang. Metode ini distandardisasi pada tahun 2010 dan hingga kini tetap menjadi bagian aktif dari semantik HTTP. Kebingungan muncul karena PATCH ditambahkan lebih belakangan dibandingkan metode lain dan sebagian framework lama tidak memiliki dukungan bawaan.

Catatan

PATCH tidak memberikan jaminan idempotensi. Menerapkan patch yang sama dua kali dapat menghasilkan hasil yang berbeda (misalnya menambahkan elemen ke sebuah list dua kali). Patch yang dilakukan secara bersamaan terhadap sumber daya yang sama berisiko menimbulkan konflik tanpa permintaan bersyarat (If-Unmodified-Since atau If-Match).

Format patch yang umum

JSON Patch menyatakan modifikasi sebagai array operasi yang berurutan: add, remove, replace, move, copy, dan test.

Content-Type: application/json-patch+json

[
  {"op":"replace","path":"/email",
   "value":"alice@example.re"},
  {"op":"add","path":"/verified","value":true}
]

JSON Merge Patch menggunakan pendekatan yang lebih sederhana. Dokumen patch mencerminkan struktur sumber daya target. Field yang ada di dalam patch akan menimpa nilai yang sudah ada. Menyetel sebuah field menjadi null akan menghapus field tersebut.

Content-Type: application/merge-patch+json

{"email":"alice@example.re","nickname":null}

Atomisitas

Server menerapkan seluruh perubahan dalam sebuah dokumen patch sebagai satu operasi atomik. Jika ada satu instruksi yang gagal, seluruh patch ditolak dan sumber daya tetap tidak berubah.

Catatan

Permintaan PATCH memiliki efek samping dan tidak dijamin idempoten. Dua patch identik yang diterapkan berurutan pada operasi “tambahkan ke list” menghasilkan hasil yang berbeda dibandingkan satu kali penerapan.

JSON Merge Patch

Klien memperbarui alamat email pengguna 42 menggunakan format JSON Merge Patch. Server menerapkan perubahan tersebut dan mengembalikan 200 OK beserta sumber daya yang telah diperbarui.

Permintaan

PATCH /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/merge-patch+json
Content-Length: 28

{"email":"alice@example.re"}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51

{"id":42,"name":"Alice","email":"alice@example.re"}

JSON Patch

Klien menerapkan dua operasi pada sebuah sumber daya konfigurasi: mengganti flag debug dan menambahkan field level logging yang baru. Server mengonfirmasi dengan 204 No Content.

Permintaan

PATCH /config/app HTTP/1.1
Host: api.example.re
Content-Type: application/json-patch+json
Content-Length: 102

[
  {"op":"replace","path":"/debug","value":false},
  {"op":"add","path":"/logLevel","value":"warn"}
]

Response

HTTP/1.1 204 No Content

Patch bersyarat

Permintaan bersyarat yang menggunakan If-Unmodified-Since mencegah modifikasi sumber daya yang sudah diubah oleh klien lain. Jika sumber daya tersebut dimodifikasi setelah stempel waktu yang diberikan, server mengembalikan 412 Precondition Failed.

Permintaan

PATCH /docs/report.json HTTP/1.1
Host: api.example.re
Content-Type: application/merge-patch+json
If-Unmodified-Since: Mon, 01 Jan 2024 12:00:00 GMT
Content-Length: 21

{"status":"reviewed"}

Response

HTTP/1.1 412 Precondition Failed
Content-Length: 0

CORS

Permintaan PATCH lintas origin selalu memicu preflight CORS. Browser terlebih dahulu mengirimkan permintaan OPTIONS untuk memastikan server mengizinkan PATCH pada sumber daya target.

PATCH vs PUT

PATCH hanya mengirimkan perubahannya saja, sehingga permintaan menjadi lebih kecil dan lebih hemat bandwidth untuk sumber daya berukuran besar. PUT mengirimkan representasi lengkap setiap kali, berapa pun jumlah field yang berubah.

PUT bersifat idempoten. Mengirimkan permintaan PUT yang sama dua kali menghasilkan state server yang sama. PATCH tidak dijamin idempoten karena operasi seperti menambahkan elemen ke sebuah list menghasilkan hasil yang berbeda pada setiap penerapan.

Gunakan PATCH ketika memperbarui field tertentu pada sumber daya yang sudah ada. Gunakan PUT ketika mengganti seluruh sumber daya dengan representasi yang baru.

PATCH vs POST

PATCH memodifikasi sumber daya yang sudah ada pada URI yang diketahui. POST membuat sumber daya baru atau memicu pemrosesan di sisi server.

PATCH menggunakan semantik patch yang terdefinisi seperti JSON Patch dan JSON Merge Patch. POST mendelegasikan semantik sepenuhnya kepada server tanpa format yang ditentukan untuk body permintaan.