Чи погана практика для визначення об’єкта API містити сторонні посилання Id як властивості?

Подобається це:

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"

Я стурбований посиланнямId .

Домен системи - це платформа, яка багато в чому інтегрується з третіми сторонами шляхом експорту даних та імпорту різних форматів (xml, excel). Він достатньо зрілий, щоб дозволити третім сторонам інтегруватися з нашою системою через API, і дизайн цього API - це те, що спонукає до цього питання.

У нас є об’єкт - Кампанія, який має ідентифікатор, який можна використовувати для ідентифікації та отримання ресурсу. Споживачі нашого API можуть мати власний довідковий код того, що вони вважають Кампанією у своєму домені.

В нашій системі є й інші об'єкти із сторонніми довідковими полями, як це, і це очікується від наших існуючих споживачів. Однак я хвилююся, що це покладає на нас тягар картографування, і ми не знаємо, що це за referenceId (число, текст, json?), І це додає ще одне заплутане властивість API для нових споживачів.

Чи вважається поганою практикою чи поганим дизайном допускати сторонні посилання Id Id у визначеннях загального об'єкта для API?

Це не проблема; це необхідність. Відсутність цього поля буде проблематичною для інтеграції із системами клієнтів.

Існує маса випадків загального користування для подібних речей. Наприклад, API, який передбачає виставлення рахунків, швидше за все, дозволить компаніям вказувати свої власні номери рахунків-фактур, програмне забезпечення для управління робочою силою потребує вас, щоб мати можливість вводити власні ідентифікатори місцевих службовців тощо.

Найпростіший дизайн, щоб уникнути будь-яких проблем - це просто не брати на себе відповідальність за поле. Просто надайте його та дозвольте клієнтам використовувати його, якщо вони захочуть. Не перевіряйте його та не використовуйте його за власною логікою, оскільки це (навіть із функціоналом, який здається хорошим) може заплутати вас у власних дизайнерських проблемах чи помилках, а також створювати специфічні очікування або запити щодо функцій постачальника. Звичайно , не використовуйте це значення як ідентифікатор внутрішньо. Показана вами структура даних передбачає, що це такий підхід.

Що стосується форматів, це просто потрібно бути вседозволеним, щоб дозволити щось розумне, і тоді вам не потрібно дбати про те, що в ньому є. Це те, що ви зробили, зробивши його рядковим полем.

Для мене ім’я referenceID не так зрозуміло. Я можу назвати це чимось на зразок customerLocalID. Але знову ж таки, можливо, ваша термінологія має сенс у вашому домені. У будь-якому випадку, я не бачу проблем для нових клієнтів, якщо поле чітко зафіксовано (особливо підкреслюючи, що це необов'язково).

Я не думаю, що існує найкраща практика щодо цього. Тримати непрозорі referenceIdу вашій системі потрібно або не залежно від вашого стосунку з сторонніми клієнтами.

Строго кажучи, швидше за все, не відповідальність вашої системи проводити розташування між вашою моделлю та третьою моделлю. Це їхнє. Ви просто допомагаєте їм зробити це картографування, утримуючи це referenceId.

Але знову ж таки, якщо це частина вашого договору між вами та ними, тоді ви повинні зберегти свою частину угоди і надати цю непрозору власність.

Сторонні посилання - це гарна ідея, коли будь-які конкретні дані належать третій стороні, а ви просто зберігач.

Також надзвичайно корисно встановити механізм ідентифікації для записів / оновлень.

Отже, у першій частині важливо встановити договір навколо цієї посилання. Якщо він унікальний, то застосуйте його за допомогою відповідних логічних кодів та кодів попередження / помилки під час запису.

Для гнучкості посилання посилаються на довільні рядки.

Крім того, я рекомендую також використовувати внутрішні ідентифікатори, як ви це зробили, тому моя модель даних не залежить від конкретного формату для ключів.

Всі внутрішні посилання потім використовуватимуть внутрішній ідентифікатор. Це також краще вписується у світ REST, який може робити такі речі, як застосувати ідентифікатор, що відповідає URL, див. Наступний пункт.

У зовнішньому API дозволяйте запити, використовуючи будь-який ідентифікатор. Ви можете зробити це з окремою кінцевою точкою або (у світі REST), використовуючи параметр запиту.

Повторне виявлення, використовуючи унікальний зовнішній ідентифікатор, дозволяє виявити повторні спроби створення запису, уникаючи помилок "подвійного запису". Для мене це чітка причина не лише підтримувати цю концепцію, але робити її обов'язковою, якщо можете.

Якщо ви не можете використовувати ідентифікатори операційних операцій / ідентифікатори повідомлення, але це не входить у питання.