É uma prática recomendada que uma definição de objeto de API contenha IDs de referência de terceiros como propriedades?

Como isso:

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"

Estou preocupado com o referenceId .

O domínio do sistema é uma plataforma que é integrada a terceiros de várias maneiras através da exportação e importação de dados de vários formatos (xml, excel). Ele é maduro o suficiente para permitir que terceiros se integrem ao nosso sistema por meio de uma API e o design dessa API é o que leva a essa pergunta.

Temos um objeto, uma campanha, que possui um ID que pode ser usado para identificar e recuperar o recurso. Os consumidores de nossa API podem ter seu próprio código de referência para o que consideram uma campanha em seu domínio.

Existem outros objetos em nosso sistema com campos de referência de terceiros como esse e é esperado de nossos consumidores existentes. No entanto, eu me preocupo que isso imponha o ônus do mapeamento e não sabemos o que é esse referenceId (número, texto, json?) E adiciona outra propriedade confusa à API para novos consumidores.

É considerado má prática ou design inadequado permitir campos de ID de referência de terceiros nas definições de objeto público para uma API?

Isso não é um problema; é uma necessidade. A falta desse campo seria problemática para a integração com os sistemas do cliente.

Existem muitos casos de uso comuns para esse tipo de coisa. Por exemplo, é provável que uma API que envolva cobrança permita às empresas especificar seus próprios números de fatura, o software de gerenciamento de força de trabalho precisa que você possa inserir seus próprios IDs de funcionários locais etc.

O projeto mais direto para evitar preocupações é simplesmente não assumir nenhuma responsabilidade pelo campo. Basta fornecer e permitir que os clientes o usem, se assim o desejarem. Não o valide ou use em sua própria lógica, pois isso (mesmo com a funcionalidade que parece boa) pode envolver você nos problemas ou bugs de design do cliente, além de criar expectativas específicas do fornecedor ou solicitações de recursos. Certamente não use esse valor como um ID internamente. A estrutura de dados que você mostrou implica que esta é a abordagem que você está adotando.

Em termos de formatos, ele só precisa ser permissivo o suficiente para permitir algo razoável, e então você não precisa se preocupar com o que está nele. Isto é o que você fez, tornando-o um campo de string.

Para mim, o nome referenceID não é tão claro. Eu poderia chamá-lo de algo como customerLocalID. Mas, novamente, talvez sua terminologia faça sentido em seu domínio. De qualquer forma, não vejo problemas para novos clientes, desde que o campo esteja claramente documentado (destacando especialmente que é opcional).

Não acho que exista uma prática recomendada em relação a isso. Manter um referenceIdsistema opaco no seu sistema é necessário ou não, dependendo da sua relação com os clientes de terceiros.

Estritamente falando, muito provavelmente, não é responsabilidade do seu sistema mapear entre o modelo e o modelo de terceiros. É deles. Você apenas os ajuda a fazer esse mapeamento mantendo isso referenceId.

Mas, novamente, se isso faz parte do seu contrato entre você e eles, você deve manter sua parte na barganha e fornecer essa propriedade opaca.

Referências de terceiros são uma boa idéia de onde dados particulares pertencem a terceiros e você é apenas um custodiante.

Também é extremamente útil estabelecer um mecanismo de idempotência para gravações / atualizações.

Portanto, na primeira parte, é importante estabelecer o contrato em torno dessa referência. Se for exclusivo, imponha-o com a lógica apropriada e os códigos de aviso / erro na gravação.

Para flexibilidade, é típico que as referências sejam seqüências arbitrárias.

Além disso, eu recomendo usar identificadores internos também, como você fez, para que meu modelo de dados não seja dependente de nenhum formato específico para chaves.

Todas as referências internas usarão o identificador interno. Isso também se encaixa melhor no mundo REST, que pode fazer coisas como aplicar IDs alinhados com o URL, veja o próximo ponto.

Na API externa, permita consultas usando um dos identificadores. Você pode fazer isso com um terminal separado ou (no mundo REST) ​​usando um parâmetro de consulta.

Com a idempotência, usando um identificador externo exclusivo, é possível detectar tentativas repetidas para criar um registro, evitando erros de "gravação dupla". Para mim, esse é o motivo claro de não apenas apoiar o conceito, mas torná-lo obrigatório, se você puder.

Falha ao usar os IDs de transação da operação / IDs da mensagem, mas isso está fora do escopo da pergunta.