web-dev-qa-db-ja.com

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フィールドを許可することは、不適切な手法または不適切な設計と見なされますか？

restapidomain-driven-designapi-designsingle-responsibility
9
jezpez

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

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

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

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

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

13
user82096

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

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

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

1
Constantin Galbenu

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

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

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

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

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

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

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

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

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

0
emperorz