Working with Versions

A Generic, General Purpose Research Data Repository Service.

Documentation

Metadata Handling

Data Handling

Appendix

Messaging

Audit Information

Working with Versions

Audit and versioning support are seamlessly integrated into the internal workflows and you can benefit from it easily. If you go back to the example of how to «ChapterGetResource,get a Data Resource» you’ll find in the response header the property ‘Resource-Version’ with a value of 1. If you scroll down to the second GET operation performed after updating the resource, you’ll see that ‘Resource-Version’ has been increased to 2. Additionally, a version number larger than 0 tells you, that versioning is enabled. If not, the version number will be 0, whereas the initial version of a resource is 1.

Now, how can you benefit from this. At first, you might be interested to get all changes applied to a resource. The following request delivers this information. You simply refer to the resource for which you want to obtain audit information and provide in the ‘Accept’ header the value ‘application/vnd.datamanager.audit+json’.

$ curl 'http://localhost:8080/api/v1/audit/edbf964c-f215-4fc6-9ef1-2ff1ea5a811e' -i -X GET \
    -H 'Accept: application/vnd.datamanager.audit+json'

As a result you receive a list of changes in a format, which is proprietary to JaVers but which also contains all information in a clear JSON format. Changes are returned ordered by version in decreasing order.

HTTP/1.1 200 OK
Resource-Version: 4
Content-Type: application/vnd.datamanager.audit+json
Content-Length: 10815

[ {
  "changeType" : "ValueChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:07.296",
    "commitDateInstant" : "2022-03-25T12:47:07.296496500Z",
    "id" : 4.0
  },
  "property" : "publisher",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : "SELF",
  "right" : "KIT Data Manager"
}, {
  "changeType" : "ValueChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:07.296",
    "commitDateInstant" : "2022-03-25T12:47:07.296496500Z",
    "id" : 4.0
  },
  "property" : "lastUpdate",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : "2022-03-25T12:47:07.152Z",
  "right" : "2022-03-25T12:47:07.289Z"
}, {
  "changeType" : "SetChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:07.159",
    "commitDateInstant" : "2022-03-25T12:47:07.159494500Z",
    "id" : 3.0
  },
  "property" : "alternateIdentifiers",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "elementChanges" : [ {
    "elementChangeType" : "ValueAdded",
    "index" : null,
    "value" : {
      "entity" : "edu.kit.datamanager.entities.Identifier",
      "cdoId" : 2
    }
  } ]
}, {
  "changeType" : "ValueChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:07.159",
    "commitDateInstant" : "2022-03-25T12:47:07.159494500Z",
    "id" : 3.0
  },
  "property" : "lastUpdate",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : "2022-03-25T12:47:06.992Z",
  "right" : "2022-03-25T12:47:07.152Z"
}, {
  "changeType" : "ValueChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.996",
    "commitDateInstant" : "2022-03-25T12:47:06.996498700Z",
    "id" : 2.0
  },
  "property" : "publicationYear",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : "2022",
  "right" : "2017"
}, {
  "changeType" : "ValueChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.996",
    "commitDateInstant" : "2022-03-25T12:47:06.996498700Z",
    "id" : 2.0
  },
  "property" : "lastUpdate",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : "2022-03-25T12:47:06.093Z",
  "right" : "2022-03-25T12:47:06.992Z"
}, {
  "changeType" : "NewObject",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  }
}, {
  "changeType" : "InitialValueChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "id",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : null,
  "right" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
}, {
  "changeType" : "ReferenceChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "identifier",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : null,
  "right" : {
    "entity" : "edu.kit.datamanager.repo.domain.PrimaryIdentifier",
    "cdoId" : 1
  }
}, {
  "changeType" : "SetChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "creators",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "elementChanges" : [ {
    "elementChangeType" : "ValueAdded",
    "index" : null,
    "value" : {
      "entity" : "edu.kit.datamanager.repo.domain.Agent",
      "cdoId" : 1
    }
  } ]
}, {
  "changeType" : "SetChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "titles",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "elementChanges" : [ {
    "elementChangeType" : "ValueAdded",
    "index" : null,
    "value" : {
      "entity" : "edu.kit.datamanager.repo.domain.Title",
      "cdoId" : 1
    }
  } ]
}, {
  "changeType" : "InitialValueChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "publisher",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : null,
  "right" : "SELF"
}, {
  "changeType" : "InitialValueChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "publicationYear",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : null,
  "right" : "2022"
}, {
  "changeType" : "ReferenceChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "resourceType",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : null,
  "right" : {
    "entity" : "edu.kit.datamanager.repo.domain.ResourceType",
    "cdoId" : 1
  }
}, {
  "changeType" : "SetChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "dates",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "elementChanges" : [ {
    "elementChangeType" : "ValueAdded",
    "index" : null,
    "value" : {
      "entity" : "edu.kit.datamanager.repo.domain.Date",
      "cdoId" : 1
    }
  } ]
}, {
  "changeType" : "SetChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "alternateIdentifiers",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "elementChanges" : [ {
    "elementChangeType" : "ValueAdded",
    "index" : null,
    "value" : {
      "entity" : "edu.kit.datamanager.entities.Identifier",
      "cdoId" : 1
    }
  } ]
}, {
  "changeType" : "InitialValueChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "lastUpdate",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : null,
  "right" : "2022-03-25T12:47:06.093Z"
}, {
  "changeType" : "InitialValueChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "state",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "left" : null,
  "right" : "VOLATILE"
}, {
  "changeType" : "SetChange",
  "globalId" : {
    "entity" : "edu.kit.datamanager.repo.domain.DataResource",
    "cdoId" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e"
  },
  "commitMetadata" : {
    "author" : "SELF",
    "properties" : [ ],
    "commitDate" : "2022-03-25T13:47:06.329",
    "commitDateInstant" : "2022-03-25T12:47:06.329725300Z",
    "id" : 1.0
  },
  "property" : "acls",
  "propertyChangeType" : "PROPERTY_VALUE_CHANGED",
  "elementChanges" : [ {
    "elementChangeType" : "ValueAdded",
    "index" : null,
    "value" : {
      "entity" : "edu.kit.datamanager.repo.domain.acl.AclEntry",
      "cdoId" : 1
    }
  } ]
} ]

In the example you can see three changes (starting with the last entry):

  1. The value of property publicationYear has been changed from 2019 (left) to 2017 (right) by the user with id SELF (which is the service itself as we are not using authentication). The result is version 2.
  2. The set alternateIdentifiers has been changed by adding the value at index 2. The result is version 3.
  3. The value of property publicationYear has been changed back from 2017 to 2019, resulting in the current version 4 of the resource.

Of course, the number of changes can be huge. Therfore, also the listing of audit information supports pagination as explained above for the basic examples.

Now, what about obtaining a specific version of a resource. This is done as shown in the next request.

$ curl 'http://localhost:8080/api/v1/dataresources/edbf964c-f215-4fc6-9ef1-2ff1ea5a811e?version=2' -i -X GET

The only thing you have to do is to add a query parameter with name ‘version’ and the value of the requested version to your GET request. As a result, you’ll receive the resource state at the specified version, which is also stated by the ‘Resource-Version’ header.

HTTP/1.1 200 OK
ETag: "-1248647055"
Resource-Version: 2
Content-Type: application/json
Content-Length: 1002

{
  "id" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e",
  "identifier" : {
    "id" : 1,
    "value" : "(:tba)",
    "identifierType" : "DOI"
  },
  "creators" : [ {
    "id" : 1,
    "familyName" : "Doe",
    "givenName" : "John",
    "affiliations" : [ "Karlsruhe Institute of Technology" ]
  } ],
  "titles" : [ {
    "id" : 1,
    "value" : "Most basic resource for testing",
    "titleType" : "OTHER"
  } ],
  "publisher" : "SELF",
  "publicationYear" : "2017",
  "resourceType" : {
    "id" : 1,
    "value" : "testingSample",
    "typeGeneral" : "DATASET"
  },
  "dates" : [ {
    "id" : 1,
    "value" : "2022-03-25T12:47:06Z",
    "type" : "CREATED"
  } ],
  "alternateIdentifiers" : [ {
    "id" : 1,
    "value" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e",
    "identifierType" : "INTERNAL"
  } ],
  "lastUpdate" : "2022-03-25T12:47:06.992Z",
  "state" : "VOLATILE",
  "acls" : [ {
    "id" : 1,
    "sid" : "SELF",
    "permission" : "ADMINISTRATE"
  } ]
}

If you omit the version argument, you always get the most recent version of the resource, in our example it’s version 4 as shown below.

HTTP/1.1 200 OK
ETag: "-2010363665"
Resource-Version: 4
Content-Type: application/json
Content-Length: 1105

{
  "id" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e",
  "identifier" : {
    "id" : 1,
    "value" : "(:tba)",
    "identifierType" : "DOI"
  },
  "creators" : [ {
    "id" : 1,
    "familyName" : "Doe",
    "givenName" : "John",
    "affiliations" : [ "Karlsruhe Institute of Technology" ]
  } ],
  "titles" : [ {
    "id" : 1,
    "value" : "Most basic resource for testing",
    "titleType" : "OTHER"
  } ],
  "publisher" : "KIT Data Manager",
  "publicationYear" : "2017",
  "resourceType" : {
    "id" : 1,
    "value" : "testingSample",
    "typeGeneral" : "DATASET"
  },
  "dates" : [ {
    "id" : 1,
    "value" : "2022-03-25T12:47:06Z",
    "type" : "CREATED"
  } ],
  "alternateIdentifiers" : [ {
    "id" : 1,
    "value" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e",
    "identifierType" : "INTERNAL"
  }, {
    "id" : 2,
    "value" : "resource-1-231118",
    "identifierType" : "OTHER"
  } ],
  "lastUpdate" : "2022-03-25T12:47:07.289Z",
  "state" : "VOLATILE",
  "acls" : [ {
    "id" : 1,
    "sid" : "SELF",
    "permission" : "ADMINISTRATE"
  } ]
}

As mentioned at the beginning, versioning is supported for metadata resources, e.g. data resources and content information. There is currently no support for versioning of the actual content.