Est-ce une mauvaise pratique qu'une définition d'objet API contienne des ID de référence tiers en tant que propriétés?

Comme ça:

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"

Je suis préoccupé par le referenceId .

Le domaine du système est une plate-forme qui est intégrée avec des tiers à bien des égards par le biais d'exportations et d'importations de données de différents formats (xml, excel). Il est suffisamment mature pour permettre à des tiers de s'intégrer à notre système via une API et la conception de cette API est ce qui pose cette question.

Nous avons un objet, une campagne, qui a un identifiant qui peut être utilisé pour identifier et récupérer la ressource. Les consommateurs de notre API peuvent avoir leur propre code de référence pour ce qu'ils considèrent comme une campagne dans leur domaine.

Il existe d'autres objets dans notre système avec des champs de référence tiers comme celui-ci et il est attendu de nos consommateurs existants. Cependant, je crains que cela nous impose le fardeau de la cartographie et que nous ne savons pas ce que est ce referenceId (nombre, texte, json?) Et qu'il ajoute une autre propriété déroutante à l'API pour les nouveaux consommateurs.

Est-il considéré comme une mauvaise pratique ou une mauvaise conception d'autoriser les champs d'ID de référence tiers dans les définitions d'objet public pour une API?

Ce n'est pas un problème; c'est une nécessité. L'absence de ce domaine serait problématique pour l'intégration avec les systèmes clients.

Il existe de nombreux cas d'utilisation courants pour ce genre de chose. Par exemple, une API impliquant la facturation est susceptible de permettre aux entreprises de spécifier leurs propres numéros de facture, le logiciel de gestion des effectifs a besoin de vous pour pouvoir saisir vos propres identifiants d'employés locaux, etc.

La conception la plus simple pour éviter tout problème est simplement de ne prendre aucune responsabilité sur le terrain. Il suffit de le fournir et de laisser les clients l'utiliser s'ils le souhaitent. Ne le validez pas et ne l'utilisez pas dans votre propre logique, car cela (même avec des fonctionnalités qui semblent bonnes) pourrait vous entraîner dans les problèmes de conception ou les bogues du client, ainsi que créer des attentes ou des demandes de fonctionnalités spécifiques au fournisseur. N'utilisez certainement pas cette valeur comme ID en interne. La structure de données que vous avez montrée implique que c'est l'approche que vous adoptez.

En termes de formats, il doit juste être suffisamment permissif pour permettre quoi que ce soit de raisonnable, et alors vous n'avez pas à vous soucier de ce qu'il contient. C'est ce que vous avez fait en en faisant un champ de chaîne.

Pour moi, le nom referenceID n'est pas si clair. Je pourrais l'appeler quelque chose comme customerLocalID. Mais là encore, peut-être que votre terminologie a du sens dans votre domaine. En tout cas, je ne vois pas de problème pour les nouveaux clients tant que le champ est clairement documenté (surtout en soulignant qu'il est optionnel).

Je ne pense pas qu'il existe une meilleure pratique à ce sujet. La tenue d'un opaque referenceIddans votre système est requise ou non selon votre relation avec les clients tiers.

À strictement parler, il n'est probablement pas de la responsabilité de votre système de mapper entre votre modèle et le modèle tiers. C'est le leur. Vous les aidez simplement à faire ce mappage en le maintenant referenceId.

Mais encore une fois, si cela fait partie de votre contrat entre vous et eux, vous devez respecter votre part du marché et fournir cette propriété opaque.

Les références de tiers sont une bonne idée lorsque des données particulières appartiennent à un tiers et que vous n'êtes qu'un dépositaire.

Il est également extrêmement utile d'établir un mécanisme d'idempotence pour les écritures / mises à jour.

Donc, dans la première partie, il est important d'établir le contrat autour de cette référence. S'il est unique, appliquez-le avec la logique appropriée et les codes d'avertissement / d'erreur lors de l'écriture.

Pour plus de flexibilité, il est typique que les références soient des chaînes arbitraires.

De plus, je recommande d'utiliser également des identifiants internes, comme vous l'avez fait, afin que mon modèle de données ne dépende d'aucun format particulier pour les clés.

Toutes les références internes utiliseront alors l'identifiant interne. Cela convient également mieux au monde REST qui peut faire des choses comme appliquer les identifiants en ligne avec l'URL, voir le point suivant.

Sur l'API externe, autorisez les requêtes à l'aide de l'un ou l'autre identifiant. Vous pouvez le faire avec un point de terminaison distinct ou (dans le monde REST) ​​à l'aide d'un paramètre de requête.

Concernant l'idempotence, en utilisant un identifiant externe unique, il est possible de détecter les tentatives répétées de création d'un enregistrement, en évitant les erreurs de "double écriture". Pour moi, c'est la raison évidente non seulement de soutenir le concept, mais de le rendre obligatoire, si vous le pouvez.

À défaut, vous pouvez utiliser les ID de transaction / ID de message d'opération, mais cela est hors de portée de la question.