Является ли плохой практикой для определения объекта API содержать сторонние ссылочные идентификаторы в качестве свойств?

Нравится:

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"

Я обеспокоен ссылкой .

Системный домен представляет собой платформу, которая во многих отношениях интегрируется с третьими сторонами посредством экспорта и импорта данных в различных форматах (xml, excel). Он достаточно зрелый, чтобы позволить сторонним организациям интегрироваться с нашей системой через API, и дизайн этого API - то, что вызывает этот вопрос.

У нас есть объект, Campaign, у которого есть идентификатор, который можно использовать для идентификации и извлечения ресурса. Потребители нашего API могут иметь собственный код ссылки на то, что они считают Кампанией в своем домене.

В нашей системе есть другие объекты со сторонними ссылочными полями, как это, и это ожидается от наших существующих потребителей. Однако я волнуюсь, это накладывает на нас бремя отображения, и мы не знаем, что такое этот referenceId (число, текст, json?), И это добавляет еще одно запутанное свойство в API для новых потребителей.

Считается ли плохой практикой или плохим дизайном разрешать сторонние поля ссылочных идентификаторов в определениях публичных объектов для API?

Это не является проблемой; это необходимость. Отсутствие этого поля будет проблематичным для интеграции с системами клиентов.

Есть много распространенных вариантов использования для такого рода вещей. Например, API, связанный с выставлением счетов, может позволить компаниям указывать свои собственные номера счетов, программное обеспечение для управления персоналом требует, чтобы вы могли вводить свои собственные локальные идентификаторы сотрудников и т. Д.

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

С точки зрения форматов, он должен быть достаточно разрешительным, чтобы допускать что-либо разумное, и тогда вам не нужно заботиться о том, что в нем есть. Это то, что вы сделали, сделав его строковым полем.

Для меня имя referenceID не так понятно. Я мог бы назвать это что-то вроде customerLocalID. Но опять же, может быть, ваша терминология имеет смысл в вашей области. В любом случае, я не вижу проблем для новых клиентов, если поле четко задокументировано (особенно подчеркивая, что это не обязательно).

Я не думаю, что есть лучшая практика в этом отношении. Наличие непрозрачного referenceIdв вашей системе требуется или нет в зависимости от ваших отношений со сторонними клиентами.

Строго говоря, скорее всего, ваша система не несет ответственности за соответствие между вашей моделью и моделью стороннего производителя. Это их. Вы просто помогаете им сделать это, удерживая это referenceId.

Но опять же, если это является частью вашего договора между вами и вами, вы должны сохранить свою часть сделки и предоставить эту непрозрачную собственность.

Сторонние ссылки - это хорошая идея, когда какие-либо конкретные данные принадлежат третьей стороне, а вы просто хранитель.

Также чрезвычайно полезно установить механизм идемпотентности для записи / обновления.

Итак, в первой части важно заключить договор вокруг этой ссылки. Если он уникален, то примените его с соответствующей логикой и кодами предупреждения / ошибки при записи.

Для гибкости типичными для ссылок являются произвольные строки.

Кроме того, я рекомендую также использовать внутренние идентификаторы, так как моя модель данных не зависит от какого-либо конкретного формата ключей.

Все внутренние ссылки будут использовать внутренний идентификатор. Это также лучше подходит для мира REST, который может выполнять такие действия, как применение идентификатора в строке с URL-адресом, см. Следующий пункт.

На внешнем API разрешите запросы, используя любой идентификатор. Вы можете сделать это с отдельной конечной точкой или (в мире REST) ​​с помощью параметра запроса.

По идемпотентности, используя уникальный внешний идентификатор, можно обнаружить неоднократные попытки создать запись, избегая ошибок «двойной записи». Для меня это явная причина не только поддержать концепцию, но и сделать ее обязательной, если можете.

В противном случае вы можете использовать идентификаторы транзакций операций / идентификаторы сообщений, но это выходит за рамки вопроса.