¿Es una mala práctica que una definición de objeto API contenga Id de referencia de terceros como propiedades?

Me gusta esto:

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"

Estoy preocupado por la referenciaId .

El dominio del sistema es una plataforma que se integra con terceros de muchas maneras a través de exportaciones de datos e importaciones de varios formatos (xml, excel). Es lo suficientemente maduro como para permitir que terceros se integren con nuestro sistema a través de una API y el diseño de esta API es lo que genera esta pregunta.

Tenemos un objeto, una Campaña, que tiene una identificación que se puede utilizar para identificar y recuperar el recurso. Los consumidores de nuestra API pueden tener su propio código de referencia para lo que consideran una Campaña dentro de su dominio.

Hay otros objetos en nuestro sistema con campos de referencia de terceros como este y se espera de nuestros consumidores existentes. Sin embargo, me preocupa que nos imponga la carga del mapeo y no sabemos cuál es este ID de referencia (número, texto, json?) Y agrega otra propiedad confusa a la API para los nuevos consumidores.

¿Se considera una mala práctica o un mal diseño permitir campos de Id de referencia de terceros en las definiciones de objetos públicos para una API?

Esto no es un problema; Es una necesidad. La falta de este campo sería problemático para integrarse con los sistemas del cliente.

Hay muchos casos de uso común para este tipo de cosas. Por ejemplo, es probable que una API que involucre la facturación permita a las compañías especificar sus propios números de factura, el software de administración de la fuerza laboral necesita que usted pueda ingresar sus propios ID de empleados locales, etc.

El diseño más directo para evitar cualquier preocupación es simplemente no asumir ninguna responsabilidad por el campo. Simplemente proporcione y deje que los clientes lo usen si lo desean. No lo valide ni lo use en su propia lógica, ya que hacerlo (incluso con una funcionalidad que parece buena) podría enredarlo en los propios problemas o errores de diseño del cliente, así como crear expectativas específicas del proveedor o solicitudes de características. Ciertamente , no use este valor como ID internamente. La estructura de datos que ha mostrado implica que este es el enfoque que está tomando.

En términos de formatos, solo debe ser lo suficientemente permisivo como para permitir algo razonable, y luego no tiene que preocuparse por lo que contiene. Esto es lo que has hecho convirtiéndolo en un campo de cadena.

Para mí, el nombre ID de referencia no es tan claro. Podría llamarlo algo así como customerLocalID. Pero, de nuevo, tal vez su terminología tenga sentido en su dominio. En cualquier caso, no veo un problema para los nuevos clientes siempre que el campo esté claramente documentado (especialmente destacando que es opcional).

No creo que haya una mejor práctica con respecto a esto. Mantener un opaco referenceIden su sistema es obligatorio o no, dependiendo de su relación con los clientes de terceros.

Estrictamente hablando, lo más probable es que no sea responsabilidad de su sistema mapear entre su modelo y el modelo de un tercero. Es de ellos. Simplemente ayúdalos a hacer ese mapeo manteniéndolos referenceId.

Pero nuevamente, si esto es parte de su contrato entre usted y ellos, entonces debe cumplir con su parte del trato y proporcionar esa propiedad opaca.

Las referencias de terceros son una buena idea cuando los datos particulares son propiedad de un tercero, y usted es solo un custodio.

También es extremadamente útil establecer un mecanismo de idempotencia para las escrituras / actualizaciones.

Entonces, en la primera parte, es importante establecer el contrato alrededor de esa referencia. Si es único, aplíquelo con la lógica apropiada y los códigos de advertencia / error en la escritura.

Por flexibilidad, es típico que las referencias sean cadenas arbitrarias.

Además, recomiendo usar identificadores internos también, como lo ha hecho, por lo que mi modelo de datos no depende de ningún formato particular para las claves.

Todas las referencias internas utilizarán el identificador interno. Esto también encaja mejor con el mundo REST que puede hacer cosas como aplicar id's en línea con la URL, ver el siguiente punto.

En la API externa, permita consultas utilizando cualquiera de los identificadores. Puede hacerlo con un punto final separado o (en el mundo REST) ​​utilizando un parámetro de consulta.

Re idempotencia, mediante el uso de un identificador externo único, es posible detectar intentos repetidos para crear un registro, evitando errores de "doble escritura". Para mí, esa es la razón clara para no solo apoyar el concepto, sino hacerlo obligatorio, si es posible.

Si no puede usar la identificación de la operación / identificación del mensaje, pero eso está fuera del alcance de la pregunta.