APIオブジェクトの定義にサードパーティの参照IDをプロパティとして含めるのは悪い習慣ですか?


9

このような:

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

回答:


13

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

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

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

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

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


Idから別の名前に変更する提案をありがとうございます。私はreferenceCodeを好みます。文字列の長さに制限があるオプションのフィールドとしてマークしましたが、それだけです。このパターンがシステム内の他のオブジェクトを介して実行され、子オブジェクトが独自のreferenceCodeを必要としないようにしたいのですが、それは設計上の決定です。ユースケースの例もありがとうございます。素晴らしい答えです。
jezpez 2017

1

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

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

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


0

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

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

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

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

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

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

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

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

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


1
この分野で一意性やその他のものを強制することはお勧めしません。理論的にはそれはユニークでなければなりません。なぜなら、顧客のシステムにデータ品質の問題がある場合や、顧客の要件が変更された場合、それが問題になります。あなたが制御できずにやけどをする可能性がある中途半端な状況よりも、責任を負わないことが最善です。

もちろん、それは契約次第です。私とコンスタンティンが言うように。一意性は、べき等性/重複回避に役立ちます。あなたの顧客があなたにジャンクを送っているなら、絶対にそれに頼らないでください。私は銀行システムを使用する傾向があるので、ご想像のとおり、安全性は利便性よりも重要です。
皇帝2017
弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.