Apakah praktik yang buruk untuk definisi objek API mengandung ID referensi pihak ketiga sebagai properti?

9

Seperti ini:

Campaign:
type: object
properties:
  id: 
    type: string
    description: "A GUID identifier"
  referenceId:
    type: string
    description: "A consumers identifier they have used to map their own systems logic to this object."
  name:
    type: string
    description: "'Great Campaign 2017' as an example"

Saya prihatin dengan referenceId .

Domain sistem adalah platform yang terintegrasi dengan pihak ke-3 dalam banyak hal melalui ekspor data dan impor berbagai format (xml, excel). Cukup matang untuk memungkinkan pihak ke-3 untuk berintegrasi dengan sistem kami melalui API dan desain API ini adalah apa yang mendorong pertanyaan ini.

Kami memiliki objek, Kampanye, yang memiliki id yang dapat digunakan untuk mengidentifikasi dan mengambil sumber daya. Konsumen API kami mungkin memiliki kode referensi sendiri untuk apa yang mereka anggap sebagai Kampanye dalam domain mereka.

Ada objek lain di sistem kami dengan bidang referensi pihak ke-3 seperti ini dan diharapkan dari konsumen kami yang ada. Namun saya khawatir itu menempatkan beban pemetaan pada kami dan kami tidak tahu apa itu referenceId (angka, teks, json?) Dan itu menambah properti membingungkan lainnya ke API untuk konsumen baru.

Apakah dianggap praktik yang buruk atau desain yang buruk untuk memungkinkan bidang ID rujukan pihak ketiga dalam definisi objek publik untuk API?

— jezpez
sumber

13

Ini bukan masalah; itu suatu keharusan. Kurangnya bidang ini akan bermasalah untuk diintegrasikan dengan sistem pelanggan.

Ada banyak kasus penggunaan umum untuk hal semacam ini. Misalnya, API yang melibatkan penagihan cenderung memungkinkan perusahaan menentukan nomor faktur mereka sendiri, perangkat lunak manajemen tenaga kerja mengharuskan Anda untuk dapat memasukkan ID karyawan lokal Anda sendiri, dll.

Desain yang paling mudah untuk menghindari masalah adalah tidak mengambil tanggung jawab atas bidang tersebut. Berikan saja dan biarkan pelanggan menggunakannya jika mereka mau. Jangan memvalidasi atau menggunakannya dalam logika Anda sendiri, karena melakukannya (bahkan dengan fungsionalitas yang tampaknya baik) dapat melibatkan Anda dalam masalah desain atau bug pelanggan sendiri, serta membuat harapan khusus vendor atau permintaan fitur. Tentunya jangan menggunakan nilai ini sebagai ID secara internal. Struktur data yang Anda tunjukkan menunjukkan bahwa ini adalah pendekatan yang Anda ambil.

Dalam hal format, itu hanya perlu cukup permisif untuk memungkinkan sesuatu yang masuk akal, dan kemudian Anda tidak perlu peduli apa yang ada di dalamnya. Inilah yang telah Anda lakukan dengan menjadikannya bidang string.

Bagi saya, nama ID referensi tidak begitu jelas. Saya mungkin menyebutnya sesuatu seperti customerLocalID. Tetapi sekali lagi, mungkin terminologi Anda masuk akal di domain Anda. Dalam kasus apa pun, saya tidak melihat masalah bagi pelanggan baru selama bidang tersebut didokumentasikan dengan jelas (terutama menyoroti bahwa itu opsional).

Terima kasih atas saran Anda untuk mengganti nama dari Id ke yang lain. Saya lebih suka kode referensi. Saya menandainya sebagai bidang opsional dengan batasan panjang string dan hanya itu. Saya masih khawatir pola ini akan berjalan melalui objek lain di sistem kami, dan ingin menghindari objek anak yang memerlukan kode referensi mereka sendiri, tetapi itu adalah keputusan desain. Terima kasih atas contoh penggunaannya juga. Jawaban yang sangat bagus.

— jezpez

1

Saya tidak berpikir ada praktik terbaik mengenai ini. referenceIdDiperlukan memegang buram di sistem Anda atau tidak tergantung pada hubungan Anda dengan klien pihak ke-3.

Sebenarnya, kemungkinan besar, bukan tanggung jawab sistem Anda untuk memetakan antara model Anda dan model pihak ketiga. Itu milik mereka. Anda hanya membantu mereka melakukan pemetaan dengan memegangnya referenceId.

Tetapi sekali lagi, jika ini adalah bagian dari kontrak Anda antara Anda dan mereka, maka Anda harus tetap menawar bagian Anda dan menyediakan properti yang buram itu.

— Constantin Galbenu
sumber

0

Referensi pihak ketiga adalah ide bagus di mana data tertentu dimiliki oleh pihak ketiga, dan Anda hanya seorang penjaga.

Juga sangat membantu untuk membangun mekanisme idempotensi untuk penulisan / pembaruan.

Jadi, pada bagian pertama, penting untuk membuat kontrak seputar referensi itu. Jika unik, maka jalankan dengan logika yang sesuai dan kode peringatan / kesalahan saat menulis.

Untuk fleksibilitas, tipikal untuk referensi adalah string arbitrer.

Selain itu, saya merekomendasikan untuk menggunakan pengidentifikasi internal juga, seperti yang telah Anda lakukan, jadi model data saya tidak bergantung pada format khusus untuk kunci.

Semua referensi internal kemudian akan menggunakan pengenal internal. Ini juga lebih cocok dengan dunia REST yang dapat melakukan hal-hal seperti menerapkan id in-line dengan URL, lihat poin berikutnya.

Pada API eksternal, izinkan permintaan menggunakan pengidentifikasi baik. Anda dapat melakukannya dengan titik akhir yang terpisah, atau (dalam dunia REST) menggunakan parameter kueri.

Kembali idempotensi, dengan menggunakan pengenal eksternal yang unik, adalah mungkin untuk mendeteksi upaya berulang untuk membuat catatan, menghindari kesalahan "tulis ganda". Bagi saya, itulah alasan yang jelas untuk tidak hanya mendukung konsep tersebut, tetapi membuatnya wajib, jika Anda bisa.

Gagal bahwa Anda dapat menggunakan id transaksi / id pesan operasi, tapi itu di luar cakupan pertanyaan.

— emperorz
sumber

1

Saya tidak akan merekomendasikan menegakkan keunikan atau apa pun di lapangan. Bahkan jika secara teori itu harus unik. Karena kemudian jika sistem pelanggan memiliki masalah kualitas data atau mereka mengubah persyaratan mereka, itu menjadi masalah Anda. Sebaiknya Anda tidak mengambil tanggung jawab, alih-alih situasi setengah jalan di mana Anda tidak memegang kendali tetapi bisa terbakar.

Tentu, itu tergantung kontrak. Seperti yang aku, dan Konstantin katakan. Keunikan dapat membantu dengan idempotensi / penghindaran duplikat. Jika pelanggan Anda mengirimi Anda sampah, maka sama sekali tidak bergantung padanya. Saya cenderung bekerja dengan sistem perbankan, jadi seperti yang Anda bayangkan, keamanan lebih penting daripada kenyamanan.

— emperorz