PUT

Penggunaan

Request PUT memberi tahu server untuk menyimpan representasi yang disertakan pada URI yang ditentukan. Jika sumber daya sudah ada, server mengganti seluruh statusnya dengan representasi yang baru. Jika tidak ada sumber daya pada URI tersebut, server membuatnya.

Idempotensi

PUT bersifat idempoten. Mengirim request PUT yang sama berkali-kali menghasilkan status server yang sama seperti mengirim request itu sekali saja. Ini berbeda dengan POST, yang pengirimannya secara berulang membuat sumber daya duplikat atau memicu pemrosesan beberapa kali.

Idempotensi membuat PUT aman untuk dicoba ulang setelah kegagalan jaringan. Klien yang tidak yakin apakah request sebelumnya sudah sampai dapat mengirim request itu lagi tanpa risiko efek samping yang tidak diinginkan.

Negosiasi konten

Server memvalidasi representasi yang masuk terhadap batasannya sendiri. Ketika Content-Type sesuai ekspektasi dan kontennya berbentuk benar, server menyimpan sumber daya dan merespons dengan 201 Created untuk sumber daya baru atau 200 OK / 204 No Content untuk penggantian.

Ketika tipe media tidak kompatibel, server mengembalikan 415 Unsupported Media Type. Respons 409 Conflict menandakan konflik status yang tidak berkaitan dengan tipe konten, misalnya ketidakcocokan versi.

PUT dibanding POST

POST mendelegasikan pemrosesan kepada sumber daya target. PUT menentukan URI persis tempat representasi itu berada. PUT ke /articles/42 menyimpan artikel tersebut di /articles/42. POST ke /articles meminta koleksi tersebut membuat artikel baru pada URI yang dipilih server.

PUT dibanding PATCH

PUT mengganti seluruh sumber daya. PATCH menerapkan modifikasi parsial. Memperbarui satu bidang dengan PUT mengharuskan pengiriman representasi lengkap. PATCH hanya mengirim perubahannya saja.

Membuat sumber daya

Klien menyimpan sebuah berkas teks biasa di /docs/setup.txt. Server membuat sumber daya tersebut dan merespons dengan 201 Created.

Request

PUT /docs/setup.txt HTTP/1.1
Host: api.example.re
Content-Type: text/plain
Content-Length: 24

Install, configure, run.

Respons

HTTP/1.1 201 Created
Location: /docs/setup.txt
Content-Length: 0

Mengganti sumber daya

Klien mengganti sumber daya JSON yang sudah ada di /users/42. Server mengonfirmasi pembaruan dengan 200 OK dan mengembalikan representasi yang tersimpan.

Request

PUT /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/json
Content-Length: 43

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

Respons

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

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

Pembaruan bersyarat

Request bersyarat yang menggunakan If-Match mencegah penimpaan sumber daya yang telah diubah oleh klien lain. Nilai ETag memastikan pembaruan hanya diterapkan pada versi yang diharapkan.

Request

PUT /config/app.json HTTP/1.1
Host: api.example.re
Content-Type: application/json
If-Match: "a1b2c3"
Content-Length: 27

{"debug":false,"port":8080}

Respons

HTTP/1.1 204 No Content
ETag: "d4e5f6"

CORS

Request PUT lintas origin selalu memicu preflight CORS. Browser terlebih dahulu mengirim request OPTIONS untuk memastikan server mengizinkan PUT pada sumber daya target.

Kode status respons

201 Created menunjukkan server membuat sumber daya baru pada URI target. Ini berlaku ketika sebelumnya tidak ada sumber daya di lokasi tersebut.

200 OK mengonfirmasi bahwa sumber daya yang sudah ada telah diganti dan respons menyertakan representasi terbaru pada body.

204 No Content mengonfirmasi penggantian tanpa body respons. Ini lazim ketika klien tidak membutuhkan representasi tersimpan untuk dikembalikan.

412 Precondition Failed menunjukkan kondisi If-Match tidak terpenuhi. Nilai ETag yang diberikan klien tidak cocok dengan versi sumber daya saat ini, sehingga server menolak pembaruan untuk mencegah penimpaan perubahan yang dibuat klien lain.

409 Conflict menandakan konflik status di tingkat aplikasi yang tidak berkaitan dengan prakondisi, misalnya konflik penggabungan konten atau benturan kontrol versi yang perlu diselesaikan klien secara manual.