Skip to content

Versioning

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.

Concurrency Control

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.

Important

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.

The PATCH operation requires the query parameter ifVersionMatch to be set. The value of which can either be:

  1. 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 name of the component with id ID and we believe that the current version is 1 then we would use the following (pseudo request): 
    PATCH /api/v2/components/<ID>?ifVersionMatch=1 {"name":"New Name"}
  2. 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) GET the 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. 
    PATCH /api/v2/components/<ID>?ifVersionMatch=latest {"name":"New Name"}