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"

我担心referenceId。

系统域是一个平台，该平台通过数据导出和各种格式（xml，excel）的导入以多种方式与第三方集成。它已经足够成熟，可以允许第三方通过API与我们的系统集成，而该API的设计正是引发这一问题的原因。

我们有一个名为Campaign的对象，该对象的ID可用于识别和检索资源。我们API的消费者可能在自己的域内拥有自己的参考代码，以作为他们认为是广告系列的参考代码。

我们系统中还有其他带有第三方参考字段的对象，这是我们现有消费者所期望的。但是我担心这给我们增加了映射的负担，我们不知道这个referenceId是什么（数字，文本，json？），并且为新使用者增加了另一个令人困惑的属性。

在API的公共对象定义中允许第三方引用ID字段被视为不良做法或不良设计？

这不是问题; 这是必须的。缺少该领域对于与客户系统集成将是一个问题。

这种事情有很多常见的用例。例如，涉及计费的API可能允许公司指定自己的发票编号，劳动力管理软件需要您能够输入自己的本地员工ID，等等。

避免任何担忧的最直接的设计就是不对该领域承担任何责任。只需提供它，让客户选择就可以使用它。不要对其进行验证或将其用于自己的逻辑中，因为这样做（即使功能看起来不错）也可能使您陷入客户自己的设计问题或错误中，并可能导致特定于供应商的期望或功能要求。当然不要在内部使用此值作为ID。您显示的数据结构暗示您正在采用这种方法。

就格式而言，它只需要足够宽容即可允许任何合理的内容，然后您就不必在意其中的内容了。这是通过将其设置为字符串字段来完成的。

对我来说，名称referenceID不太清楚。我可能将其称为customerLocalID。但是话又说回来，也许您的术语在您的领域中有意义。无论如何，只要对该字段进行了明确记录（特别强调它是可选的），我就不会对新客户产生任何问题。

我认为没有最佳实践。referenceId是否需要在系统中保持不透明取决于您与第三方客户的关系。

严格来说，最有可能的是，在模型与第三方模型之间进行映射不是系统的责任。是他们的。您只需按住即可帮助他们进行映射referenceId。

但是同样，如果这是您与他们之间的合同的一部分，那么您必须保留您的合同并提供不透明的属性。

如果第三方拥有任何特定数据，则第三方参考是个好主意，而您只是托管人。

建立写/更新的幂等机制也是非常有帮助的。

因此，在第一部分中，围绕该引用建立合同很重要。如果它是唯一的，则在写入时使用适当的逻辑和警告/错误代码来实施它。

为了灵活起见，引用通常是任意字符串。

另外，我建议也像您一样使用内部标识符，因此我的数据模型不依赖于键的任何特定格式。

然后，所有内部引用将使用内部标识符。这也更适合REST世界，它可能会做一些事情，例如将id嵌入URL中，请参见下一点。

在外部API上，允许使用任一标识符进行查询。您可以使用单独的终结点，也可以（在REST环境中）使用查询参数来实现。

通过使用唯一的外部标识符，可以实现幂等性，从而可以检测到重复创建记录的尝试，从而避免了“双重写入”错误。对我来说，这是明确的理由，不仅支持该概念，而且如果可以的话，使其成为强制性的。

无法使用操作事务ID /消息ID，但这超出了问题的范围。