Нравится:
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?
Я не думаю, что есть лучшая практика в этом отношении. Наличие непрозрачного
referenceId
в вашей системе требуется или нет в зависимости от ваших отношений со сторонними клиентами.Строго говоря, скорее всего, ваша система не несет ответственности за соответствие между вашей моделью и моделью стороннего производителя. Это их. Вы просто помогаете им сделать это, удерживая это
referenceId
.Но опять же, если это является частью вашего договора между вами и вами, вы должны сохранить свою часть сделки и предоставить эту непрозрачную собственность.
источник
Сторонние ссылки - это хорошая идея, когда какие-либо конкретные данные принадлежат третьей стороне, а вы просто хранитель.
Также чрезвычайно полезно установить механизм идемпотентности для записи / обновления.
Итак, в первой части важно заключить договор вокруг этой ссылки. Если он уникален, то примените его с соответствующей логикой и кодами предупреждения / ошибки при записи.
Для гибкости типичными для ссылок являются произвольные строки.
Кроме того, я рекомендую также использовать внутренние идентификаторы, так как моя модель данных не зависит от какого-либо конкретного формата ключей.
Все внутренние ссылки будут использовать внутренний идентификатор. Это также лучше подходит для мира REST, который может выполнять такие действия, как применение идентификатора в строке с URL-адресом, см. Следующий пункт.
На внешнем API разрешите запросы, используя любой идентификатор. Вы можете сделать это с отдельной конечной точкой или (в мире REST) с помощью параметра запроса.
По идемпотентности, используя уникальный внешний идентификатор, можно обнаружить неоднократные попытки создать запись, избегая ошибок «двойной записи». Для меня это явная причина не только поддержать концепцию, но и сделать ее обязательной, если можете.
В противном случае вы можете использовать идентификаторы транзакций операций / идентификаторы сообщений, но это выходит за рамки вопроса.
источник