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の設計がこの疑問を引き起こします。

リソースを識別して取得するために使用できるIDを持つオブジェクト、キャンペーンがあります。APIの利用者は、ドメイン内のキャンペーンと見なすものへの独自の参照コードを持っている場合があります。

私たちのシステムには、このようなサードパーティの参照フィールドを持つ他のオブジェクトがあり、既存のコンシューマーから期待されています。ただし、マッピングの負担がかかり、このreferenceIdが何であるか（数値、テキスト、json？）がわからないため、新しいコンシューマー向けの混乱するプロパティがAPIに追加されます。

APIのパブリックオブジェクト定義でサードパーティの参照IDフィールドを許可することは、不適切な手法または不適切な設計と見なされますか？

これは問題ではありません。それは必需品です。このフィールドがないと、顧客システムとの統合に問題が生じます。

この種の一般的なユースケースはたくさんあります。たとえば、請求に関連するAPIは、企業が独自の請求書番号を指定できるようにする可能性が高く、労働力管理ソフトウェアは、独自のローカル従業員IDを入力できる必要があります。

懸念を回避するための最も簡単な設計は、フィールドに対する責任を負わないことです。提供するだけで、必要に応じて顧客が使用できるようにします。これを検証したり、独自のロジックで使用したりしないでください。そうすることで（良いように見える機能でも）ベンダー固有の期待や機能のリクエストを作成するだけでなく、お客様自身の設計の問題やバグに巻き込まれる可能性があります。確かに、この値を内部的にIDとして使用しないでください。あなたが示したデータ構造は、これがあなたが取っているアプローチであることを暗示しています。

フォーマットに関しては、妥当なものをすべて許可するのに十分な寛容である必要があり、その中の内容を気にする必要はありません。これは、それを文字列フィールドにすることによって行ったものです。

私にとって、referenceIDという名前はそれほど明確ではありません。私はそれをcustomerLocalIDのようなものと呼ぶかもしれません。しかし、繰り返しになりますが、多分あなたの専門用語はあなたのドメインで意味があります。いずれにしても、フィールドが明確に文書化されている限り（特に、オプションであることを強調している限り）、新しい顧客には問題はありません。

これに関してベストプラクティスがあるとは思いません。referenceIdサードパーティのクライアントとの関係に応じて、システムで不透明を保持する必要があります。

厳密に言うと、おそらくモデルとサードパーティモデルをマッピングするのはシステムの責任ではありません。それは彼らのものだよ。あなたは彼らを助けることを保持することにより、そのマッピングを行うことreferenceId。

しかし、繰り返しになりますが、これがあなたと彼らの間の契約の一部である場合は、取引の一部を維持し、その不透明なプロパティを提供する必要があります。

サードパーティの参照は、特定のデータがサードパーティによって所有されており、あなたが単なる管理者である場合に適しています。

また、書き込み/更新のべき等性のメカニズムを確立することも非常に役立ちます。

したがって、最初の部分では、その参照に関する契約を確立することが重要です。一意の場合は、書き込み時に適切なロジックと警告/エラーコードを使用して強制します。

柔軟性のために、参照は任意の文字列であることが一般的です。

さらに、以前と同じように内部識別子も使用することをお勧めします。これにより、私のデータモデルはキーの特定の形式に依存しなくなります。

すべての内部参照は内部識別子を使用します。これは、URLにインラインでIDを適用するなどの処理を行うRESTの世界にも適しています。次のポイントを参照してください。

外部APIでは、いずれかの識別子を使用したクエリを許可します。別のエンドポイントで、または（RESTの世界では）クエリパラメータを使用してそれを行うことができます。

べき等性については、一意の外部識別子を使用することで、レコードの作成の繰り返し試行を検出し、「二重書き込み」エラーを回避できます。私にとっては、それがコンセプトをサポートするだけでなく、可能であればそれを必須にする理由です。

操作トランザクションIDまたはメッセージIDを使用できることはできませんが、それは問題の範囲外です。