When working with the API, you may notice that entities (components, references, workspaces etc) have a
_version field with a numeric value.
Indeed, every time you update an entity in Ardoq, a new version of that entity is created.
When you update an entity, the Ardoq API requires that you provide (what you believe to be) the current version of the stored entity. This provided value is compared against the version of the stored entity before the update process begins. If the two versions differ then the operation will fail. This means that you can avoid updating an entity that someone else has modified since you last read it.
While the need for concurrency control will depend on your workflow, it is considered good practice to NOT opt-out when testing an integration (script) that modifies Ardoq entities. Doing so can help identify double writes and other unexpected behavior that may otherwise go unnoticed.
PATCH operation requires the query parameter
ifVersionMatch to be set. The value of which can either be:
- The current version number. The operation will fail if the stored version does not match the value provided for
ifVersionMatch. As an example - If we wanted to update the
nameof the component with id
IDand we believe that the current version is
1then we would use the following (pseudo request):
- The special string
latest. The operation will use the stored version. You might want/need to use this if you can not (or do not want to)
GETthe entity first. In this case you must still know the Ardoq Identifier (OID) for the entity. This would be the case if (for example) you store the Ardoq Identifier in an external system.