Apa pola terbaik untuk menambahkan item yang ada ke koleksi di REST API?

Saya merancang REST API pragmatis dan saya sedikit bingung tentang cara terbaik untuk menambahkan entitas yang ada ke koleksi. Model domain saya mencakup Proyek yang memiliki koleksi Situs. Ini adalah hubungan banyak-ke-banyak yang ketat dan saya tidak perlu membuat entitas yang secara eksplisit memodelkan hubungan (yaitu ProjectSite).

API saya akan memungkinkan konsumen untuk menambahkan Situs yang ada ke Proyek. Di mana saya menutup telepon adalah bahwa satu-satunya data yang saya butuhkan adalah ProjectId dan SiteId. Ide awal saya adalah:

1. POST myapi/projects/{projectId}/sites/{siteId}

Tapi saya juga memikirkannya

2. POST myapi/projects/{projectId}/sites

dengan entitas Situs yang dikirim sebagai konten JSON.

Opsi 1 sederhana dan berfungsi tetapi tidak terasa benar, dan saya memiliki hubungan lain yang tidak dapat mengikuti pola ini sehingga menambah ketidakkonsistenan pada API saya.

Opsi 2 terasa lebih baik tetapi mengarah ke dua masalah:

• Haruskah saya membuat Situs atau melemparkan pengecualian jika Situs baru diposting (SiteId = 0)?
• Karena saya hanya perlu ProjectId dan SiteId untuk membuat hubungan, situs dapat diposting dengan data yang salah atau hilang untuk properti lainnya.

Opsi ketiga adalah memberikan titik akhir sederhana hanya untuk membuat dan menghapus hubungan. Titik akhir ini akan mengharapkan muatan JSON yang hanya berisi ProjectId dan SiteId.

Apa yang kamu pikirkan?

POST adalah kata kerja "append", dan juga kata kerja "processing". PUT adalah kata kerja "buat / perbarui" (untuk pengidentifikasi yang dikenal), dan hampir terlihat seperti pilihan yang tepat di sini, karena target penuh URI diketahui. projectIddan siteIdsudah ada, jadi Anda tidak perlu "POST ke koleksi" untuk menghasilkan ID baru.

Masalah dengan PUT adalah bahwa itu membutuhkan tubuh menjadi representasi dari sumber daya yang Anda PUTting. Tetapi maksudnya di sini adalah untuk menambah sumber daya koleksi "proyek / situs", daripada memperbarui sumber daya Situs.

Bagaimana jika seseorang PUT representasi JSON lengkap dari Situs yang ada? Haruskah Anda memperbarui koleksi dan memperbarui objek? Anda bisa mendukungnya, tapi sepertinya itu bukan maksudnya. Seperti yang Anda katakan,

satu-satunya data yang benar-benar saya butuhkan adalah ProjectId dan SiteId

Sebaliknya, saya akan mencoba POSTing siteIdke koleksi, dan mengandalkan sifat "append" dan "proses" POST:

POST myapi / proyek / {projectId} / situs

{'id': '...'}

Karena Anda memodifikasi sumber daya kumpulan situs dan bukan sumber daya situs , itulah URI yang Anda inginkan. POST bisa tahu untuk "menambahkan / memproses" dan menambahkan elemen dengan id itu ke kumpulan situs proyek.

Itu masih meninggalkan pintu terbuka untuk membuat situs baru untuk proyek dengan menyempurnakan JSON dan menghilangkan id. "Tidak ada id" == "buat dari awal". Tetapi jika koleksi URI mendapatkan id dan tidak ada yang lain, cukup jelas apa yang perlu terjadi.

Pertanyaan menarik. :)

Kami menggunakan Patchmetode untuk hal-hal seperti ini. Yang ingin Anda lakukan adalah memodifikasi Proyek yang ada untuk menambahkan Situs ke dalamnya.

Jadi sesuatu seperti ini akan berhasil

PATCH myapi/projects/{id} 

dengan entitas Situs sebagai JSON / JSONArray di badan permintaan.

Dengan cara itu Anda dapat menggunakan URL yang sama untuk memodifikasi bagian-bagian berbeda dari Proyek jika Anda perlu - kode Anda dalam implementasi harus cukup cerdas untuk menangani modifikasi parsial sumber daya ini.