Konvensi

Halaman ini merangkum di satu tempat semua konvensi HTTP yang berlaku umum pada setiap permintaan dan respons saat Anda memanggil WEEGLOO API dari kode. Yang termasuk di sini adalah tipe media respons, modifikasi parsial (JSON Patch), dan header X-Weegloo-Version yang mencegah konflik modifikasi bersamaan. Endpoint untuk masing-masing resource dibahas di referensi resource terkait, sedangkan konvensi yang diikuti bersama oleh endpoint-endpoint tersebut merujuk ke halaman ini.

Tipe media respons

Respons WEEGLOO API menggunakan tipe media application/vnd.com.weegloo.v1+json;charset=UTF-8. Bukan application/json biasa.

Jangan mengirim Accept: application/json pada permintaan. Menegosiasikan tipe media dengan nilai ini tidak cocok dengan tipe vendor WEEGLOO sehingga dapat menyebabkan kegagalan seperti 406 Not Acceptable.

• Disarankan: hilangkan header Accept pada permintaan (misalnya, tidak menyertakan Accept pada fetch).
• Jika memang harus dikirim, gunakan tipe vendor yang sama dengan respons, yaitu application/vnd.com.weegloo.v1+json;charset=UTF-8.

Saat membuat instance axios atau wrapper fetch bersama, pastikan nilai default-nya tidak memaksakan Accept: application/json. (Aturan ini berlaku untuk kode aplikasi. AI agent tidak memanggil HTTP secara langsung, melainkan menggunakan tool MCP.)

Modifikasi parsial (JSON Patch)

Sebagian besar resource seperti Content, Media, dan Content Type dapat dimodifikasi sebagian secara selektif dengan PATCH. Body permintaan berupa array berformat RFC 6902 JSON Patch. Setiap item memiliki operasi op, path JSON Pointer path yang menunjuk lokasi target, dan value atau from sesuai operasinya.

Header Content-Type pada permintaan PATCH harus berupa application/json-patch+json. Bukan application/json biasa.

Berikut adalah contoh mengubah nilai satu field saja.

[
  { "op": "replace", "path": "/fields/price/en-US", "value": 16500 }
]

Untuk mengganti dengan body penuh, gunakan PUT. PUT mengganti dengan body resource penuh (atau, jika kontrak endpoint mengizinkannya, body parsial yang hanya memuat bagian yang akan diubah). Endpoint mana yang mendukung PATCH, serta apakah PUT merupakan penggantian penuh atau penggantian parsial, dapat Anda periksa pada blok endpoint di setiap halaman resource.

Kontrol konkurensi (X-Weegloo-Version)

Jika resource yang sama diubah secara bersamaan dari dua tempat, salah satu perubahan dapat menimpa perubahan yang lain. Untuk mencegahnya, WEEGLOO menggunakan kontrol konkurensi optimistis. Saat memodifikasi, menghapus, atau mengubah status sebuah resource, sertakan sys.version saat ini pada permintaan melalui header X-Weegloo-Version.

Server hanya menerima perubahan ketika nilai ini sama dengan versi saat ini yang tersimpan. Jika header hilang atau nilainya tidak cocok (misalnya karena di sela waktu itu ada orang lain yang mengubah lebih dulu sehingga versi naik), permintaan ditolak dengan error konflik WGL409005. Dalam kasus ini, kueri ulang resource untuk mendapatkan sys.version terbaru, lalu coba lagi perubahannya. Format respons error dibahas di Error.

Permintaan mana yang membutuhkannya adalah sebagai berikut.

Resource yang tidak memiliki version (ServiceUser) tidak menerima header ini. Untuk mengetahui secara persis endpoint mana yang mensyaratkan header ini, periksa requestHeaderSchema pada blok endpoint di setiap halaman resource. Makna sys.version itu sendiri dibahas di Properti sistem (sys).

Dokumen terkait

• Properti sistem (sys): sys.version yang disertakan pada X-Weegloo-Version.
• Parameter kueri umum: kueri daftar dan paginasi.
• Error: kode error seperti WGL409005.