Skip to main content

Record Revision

As Records in Tape change over time, it is important to understand what changes were made, by whom and when. Revisions can be retrieved via the API.

Revisions concept​

Every record in Tape has a revision number property that starts with 0 upon creation and is increased with each change made to the Record.

Record revisions will include the author of the revision as created_by, the date and time of the revision created_on and the revision number.

Retrieve revisions for a record​

GEThttps://api.tapeapp.com/v1/record/{record_id}/revision

The following example fetches the revisions of record with ID 1, which was created and updated once by the user Dan Jacob with ID 600:

Query paramTypeDescription
include_deletedbooleanInclude records that are deleted but still accessible via a trash (default: false)
➡️    Request
curl -X GET https://api.tapeapp.com/v1/record/1/revision  \
  -u user_key_replace_with_your_api_key:
⬅️    Response
{
  "total": 2,
  "revisions": [
    {
      "created_by": {
        "user_id": 600,
        "name": "Dan Jacob",
        "type": "user",
        "image": null
      },
      "created_on": "2022-03-16 14:25:00",
      "type": "creation",
      "revision": 0
    },
    {
      "created_by": {
        "user_id": 600,
        "name": "Dan Jacob",
        "type": "user",
        "image": null
      },
      "created_on": "2022-03-16 14:30:00",
      "type": "update",
      "revision": 1
    }
  ]
}
Note

Note that Revisions do not contain the actual changes made, but only the metadata. Use the endpoint described in the next section to fetch individual revision changes.

Retrieve revision delta​

GEThttps://api.tapeapp.com/v1/record/{record_id}/revision/previous/{toRevisionId}

In order to understand how a record changed over time, the Tape API provides consumers with the concept of Revision Deltas. Revision deltas will include a from and to property, describing the transition of individual fields from one value (or no value) to another (or none). These properties follow the same form as the record field values property, check the field value section for more details.

A single record revision may include deltas for multiple fields if the changes were made at the same time by the same entity.

The following example fetches the revision delta of revision number 1 of record with ID 1 to its previous revision number 0 to understand the changes made from the previous example. One may now see that a single text field with external_id notes was updated from no value to the value Some important notes.

➡️    Request
curl -X GET https://api.tapeapp.com/v1/record/1/revision/previous/1  \
  -u user_key_replace_with_your_api_key:
⬅️    Response
{
  "record_id": 1,
  "from_revision_id": 0,
  "to_revision_id": 1,
  "revision_deltas": [
    {
      "from": [],
      "external_id": "notes",
      "field_id": 2000,
      "label": "Notes",
      "to": [
        {
          "value": "Some important notes"
        }
      ],
      "type": "text",
      "field_type": "single_text",
      "config": {
        "description": null,
        "required": false,
        "label": "Notes"
      }
    }
  ]
}

Revision lookback limit​

Revision deltas can only be computed for the last 50 revisions of a record. Requesting a revision that lies more than 50 revisions behind the record's current revision fails with a 400 error (see Errors):

⬅️ Response
{
  "status_code": 400,
  "endpoint": "/v1/record/1/revision/previous/123",
  "error_code": "validation",
  "error_message": "Revision ID 123 is too old. You can maximally go back 50 revisions"
}