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"
I am concerned about the referenceId.
The system domain is a platform which is integrated with 3rd parties in many ways through data exports and imports of various formats (xml, excel). It is mature enough to allow 3rd parties to integrate with our system through an API and the design of this API is what prompts this question.
We have an object, a Campaign, which has an id that can be used to identify and retrieve the resource. Consumers of our API may have their own reference code to what they consider to be a Campaign within their domain.
There are other objects in our system with 3rd party reference fields like this and it's expected from our existing consumers. However I worry it puts the burden of mapping on us and we do not know what this referenceId is (number, text, json?) and it adds another confusing property to the API for new consumers.
Is it considered bad practice or bad design to allow 3rd Party reference Id fields in the public object definitions for an API?