Ist es eine schlechte Praxis, wenn eine API-Objektdefinition Referenz-IDs von Drittanbietern als Eigenschaften enthält?

So was:

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"

Ich bin besorgt über die Referenz-ID .

Die Systemdomäne ist eine Plattform, die auf vielfältige Weise durch Datenexporte und -importe in verschiedenen Formaten (XML, Excel) in Dritte integriert wird. Es ist ausgereift genug, um es Dritten zu ermöglichen, sich über eine API in unser System zu integrieren, und das Design dieser API ist der Grund für diese Frage.

Wir haben ein Objekt, eine Kampagne, die eine ID hat, mit der die Ressource identifiziert und abgerufen werden kann. Verbraucher unserer API haben möglicherweise ihren eigenen Referenzcode für eine Kampagne in ihrer Domain.

Es gibt andere Objekte in unserem System mit Referenzfeldern von Drittanbietern wie diesem, die von unseren bestehenden Verbrauchern erwartet werden. Ich mache mir jedoch Sorgen, dass dies die Last der Zuordnung für uns bedeutet und wir nicht wissen, was diese Referenz-ID ist (Nummer, Text, JSON?), Und dass sie der API eine weitere verwirrende Eigenschaft für neue Verbraucher hinzufügt.

Wird es als schlechte Praxis oder schlechtes Design angesehen, Referenz-ID-Felder von Drittanbietern in den öffentlichen Objektdefinitionen für eine API zuzulassen?

Das ist kein Problem; es ist eine Notwendigkeit. Das Fehlen dieses Feldes wäre problematisch für die Integration in Kundensysteme.

Es gibt viele gängige Anwendungsfälle für diese Art von Dingen. Beispielsweise können Unternehmen mit einer API, die die Abrechnung umfasst, wahrscheinlich ihre eigenen Rechnungsnummern angeben. Die Personalverwaltungssoftware erfordert, dass Sie Ihre eigenen lokalen Mitarbeiter-IDs eingeben können usw.

Das einfachste Design, um Bedenken zu vermeiden, besteht darin, einfach keine Verantwortung für das Feld zu übernehmen. Stellen Sie es einfach zur Verfügung und lassen Sie die Kunden es verwenden, wenn sie dies wünschen. Validieren Sie es nicht und verwenden Sie es nicht in Ihrer eigenen Logik, da dies (selbst bei Funktionen, die gut erscheinen) Sie in die eigenen Designprobleme oder Fehler des Kunden verwickeln und herstellerspezifische Erwartungen oder Funktionsanforderungen hervorrufen kann. Sicherlich diesen Wert nicht als ID verwendet intern. Die von Ihnen gezeigte Datenstruktur impliziert, dass dies der Ansatz ist, den Sie verfolgen.

In Bezug auf Formate muss es nur so tolerant sein, dass alles Vernünftige möglich ist, und dann muss es Ihnen egal sein, was darin enthalten ist. Dies haben Sie getan, indem Sie es zu einem Zeichenfolgenfeld gemacht haben.

Für mich ist der Name referenceID nicht so klar. Ich könnte es so etwas wie customerLocalID nennen. Andererseits ist Ihre Terminologie in Ihrer Domäne möglicherweise sinnvoll. Auf jeden Fall sehe ich kein Problem für Neukunden, solange das Feld klar dokumentiert ist (insbesondere wenn hervorgehoben wird, dass es optional ist).

Ich glaube nicht, dass es diesbezüglich eine bewährte Methode gibt. referenceIdAbhängig von Ihrer Beziehung zu Kunden von Drittanbietern ist es erforderlich, eine undurchsichtige Funktion in Ihrem System zu halten oder nicht.

Genau genommen liegt es höchstwahrscheinlich nicht in der Verantwortung Ihres Systems, eine Zuordnung zwischen Ihrem Modell und dem Modell eines Drittanbieters vorzunehmen. Es gehört ihnen. Sie helfen ihnen nur bei der Zuordnung, indem Sie sie gedrückt halten referenceId.

Wenn dies jedoch Teil Ihres Vertrags zwischen Ihnen und ihnen ist, müssen Sie Ihren Teil des Geschäftes behalten und dieses undurchsichtige Eigentum bereitstellen.

Referenzen von Drittanbietern sind eine gute Idee, wenn bestimmte Daten dem Drittanbieter gehören und Sie nur eine Depotbank sind.

Es ist auch äußerst hilfreich, einen Mechanismus für die Idempotenz für Schreibvorgänge / Aktualisierungen einzurichten.

Daher ist es im ersten Teil wichtig, den Vertrag um diese Referenz herum zu schließen. Wenn es eindeutig ist, erzwingen Sie es beim Schreiben mit der entsprechenden Logik und den entsprechenden Warn- / Fehlercodes.

Aus Gründen der Flexibilität sind die Referenzen normalerweise beliebige Zeichenfolgen.

Darüber hinaus empfehle ich, wie Sie auch interne Bezeichner zu verwenden, damit mein Datenmodell nicht von einem bestimmten Format für Schlüssel abhängig ist.

Alle internen Referenzen verwenden dann die interne Kennung. Dies passt auch besser zur REST-Welt, in der beispielsweise IDs in Übereinstimmung mit der URL angewendet werden können (siehe nächster Punkt).

Lassen Sie auf der externen API Abfragen mit beiden Bezeichnern zu. Sie können dies mit einem separaten Endpunkt oder (in der REST-Welt) mithilfe eines Abfrageparameters tun.

Durch die Verwendung einer eindeutigen externen Kennung können wiederholte Versuche zum Erstellen eines Datensatzes erkannt werden, wodurch Fehler beim "doppelten Schreiben" vermieden werden. Für mich ist das der klare Grund, das Konzept nicht nur zu unterstützen, sondern es, wenn möglich, verbindlich zu machen.

Andernfalls können Sie die Transaktions-IDs / Nachrichten-IDs der Operation verwenden, dies ist jedoch nicht Gegenstand der Frage.