È una cattiva pratica per una definizione di oggetto API contenere ID di riferimento di terze parti come proprietà?

Come questo:

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"

Sono preoccupato per il riferimentoId .

Il dominio di sistema è una piattaforma che è integrata con terze parti in molti modi attraverso l'esportazione e l'importazione di dati di vari formati (XML, Excel). È abbastanza maturo per consentire a terze parti di integrarsi con il nostro sistema tramite un'API e la progettazione di questa API è ciò che fa sorgere questa domanda.

Abbiamo un oggetto, una campagna, che ha un ID che può essere utilizzato per identificare e recuperare la risorsa. I consumatori della nostra API possono avere il proprio codice di riferimento a quella che considerano una campagna all'interno del proprio dominio.

Ci sono altri oggetti nel nostro sistema con campi di riferimento di terze parti come questo ed è previsto dai nostri consumatori esistenti. Tuttavia, mi preoccupo che ci pesa sulla mappatura e non sappiamo quale sia questo riferimento (numero, testo, json?) E aggiunge un'altra proprietà confusa all'API per i nuovi consumatori.

È considerata una cattiva pratica o una cattiva progettazione consentire i campi ID di riferimento di terze parti nelle definizioni degli oggetti pubblici per un'API?

Questo non è un problema; è una necessità. La mancanza di questo campo sarebbe problematica per l'integrazione con i sistemi dei clienti.

Ci sono molti casi d'uso comuni per questo genere di cose. Ad esempio, un'API che coinvolge la fatturazione probabilmente consentirà alle aziende di specificare i propri numeri di fattura, il software di gestione della forza lavoro richiede che tu sia in grado di inserire i tuoi ID dipendenti locali, ecc.

Il progetto più semplice per evitare qualsiasi preoccupazione è semplicemente quello di non assumersi alcuna responsabilità per il campo. Forniscilo e lascia che i clienti lo utilizzino se lo desiderano. Non convalidarlo o utilizzarlo secondo la tua logica, poiché farlo (anche con funzionalità che sembra buona) potrebbe coinvolgerti nei problemi di progettazione o nei bug del cliente, oltre a creare aspettative specifiche del fornitore o richieste di funzionalità. Certamente non usare questo valore come ID internamente. La struttura dei dati che hai mostrato implica che questo è l'approccio che stai adottando.

In termini di formati, deve solo essere abbastanza permissivo da consentire qualcosa di ragionevole, e quindi non devi preoccuparti di cosa ci sia dentro. Questo è ciò che hai fatto rendendolo un campo stringa.

Per me, il nome referenceID non è così chiaro. Potrei chiamarlo qualcosa di simile a customerLocalID. Ma poi di nuovo, forse la tua terminologia ha senso nel tuo dominio. In ogni caso, non vedo alcun problema per i nuovi clienti, purché il campo sia chiaramente documentato (soprattutto evidenziando che è facoltativo).

Non penso che ci sia una buona pratica al riguardo. referenceIdÈ necessario disporre di un opaco nel sistema in base alla relazione con i clienti di terze parti.

A rigor di termini, molto probabilmente, non è responsabilità del tuo sistema mappare tra il tuo modello e il modello di terze parti. È loro. Li aiuti a fare quella mappatura tenendolo referenceId.

Ma ancora una volta, se questo fa parte del tuo contratto tra te e loro, allora devi mantenere la tua parte dell'affare e fornire quella proprietà opaca.

I riferimenti di terze parti sono una buona idea in cui qualsiasi dato particolare è di proprietà della terza parte e tu sei solo un custode.

È anche estremamente utile stabilire un meccanismo di idempotenza per scritture / aggiornamenti.

Pertanto, nella prima parte, è importante stabilire il contratto attorno a tale riferimento. Se è univoco, applicalo con la logica appropriata e i codici di avviso / errore in scrittura.

Per flessibilità, è tipico che i riferimenti siano stringhe arbitrarie.

Inoltre, ti consiglio di utilizzare anche identificatori interni, come hai fatto tu, quindi il mio modello di dati non dipende da alcun formato particolare per le chiavi.

Tutti i riferimenti interni utilizzeranno quindi l'identificatore interno. Questo si adatta anche meglio al mondo REST che può fare cose come applicare l'id in linea con l'URL, vedere il punto successivo.

Sull'API esterna, consentire le query utilizzando l'identificatore. È possibile farlo con un endpoint separato o (nel mondo REST) ​​utilizzando un parametro di query.

Per quanto riguarda l'idempotenza, utilizzando un identificatore esterno univoco, è possibile rilevare ripetuti tentativi di creazione di un record, evitando errori di "doppia scrittura". Per me, questa è la chiara ragione per non solo supportare il concetto, ma renderlo obbligatorio, se puoi.

Non è possibile utilizzare l'ID operazione transazione / ID messaggio, ma non rientra nell'ambito della domanda.