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

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 di uso comune per questo genere di cose. Ad esempio, è probabile che un'API che coinvolge la fatturazione consenta alle aziende di specificare i propri numeri di fattura, il software di gestione della forza lavoro deve poter inserire i propri ID dei dipendenti locali, ecc.

Il design più semplice per evitare qualsiasi preoccupazione è semplicemente non assumersi alcuna responsabilità per il campo. Basta fornirlo e lasciare che i clienti lo usino se lo desiderano. Non convalidarlo o usarlo nella tua logica, in quanto farlo (anche con una funzionalità che sembra buona) potrebbe intrappolarti nei problemi di progettazione o nei bug del cliente, oltre che creare aspettative specifiche del fornitore o richieste di funzionalità. Certamente non utilizzare questo valore come ID internamente. La struttura dei dati che hai mostrato implica che questo è l'approccio che stai prendendo.

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

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

Non penso che ci sia una buona pratica in merito. Mantenere un opaco referenceId nel tuo sistema è richiesto o meno in base alla tua relazione con i clienti di terze parti.

In senso stretto, molto probabilmente, non è responsabilità del tuo sistema mappare tra il tuo modello e il modello di terze parti. È loro. Devi solo aiutarli a eseguire tale mappatura trattenendo referenceId .

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

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

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

Quindi, nella prima parte, è importante stabilire il contratto attorno a quel riferimento. Se è univoco, applicalo con la logica appropriata e i codici di avviso / errore su write.

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

Inoltre, mi raccomando di utilizzare anche gli identificatori interni, così come è stato fatto, quindi il mio modello di dati non dipende da un particolare formato per le chiavi.

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

Sull'API esterna, consenti le query utilizzando l'identificatore. Puoi farlo con un endpoint separato o (nel mondo REST) usando un parametro di query.

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

Se non riesci a utilizzare gli ID id / messaggi della transazione operativa, ma ciò non rientra nell'ambito della domanda.