iQ Revisions

[#1]

This article describes how to use the iQ Revisions API. A revision is a saved version of your iQ profile. The revision status contains information about the version, such as published environments, user comments, timestamps, and checksums for the JavaScript files generated. A zip file containing the published files related to the revision is called a revision bundle.

In this article:

Table of Contents Placeholder 

Prerequisites

The iQ Revisions API must be activated for your account before it will return revision information. Contact Support Desk to request the activation.

How it Works

A new revision is created each time a Save as action is performed. As each version is updated or published, the status is reflected in the revision. 

Authentication

The bearer token is used to authenticate all API calls and not the API key. The API key is only used in the authentication call. 

See the Getting Started guide to learn about generating a bearer token from the API key.

Revision Fields

Revisions are returned as JSON objects that contain the following fields:

Object Name	Type	Description
revision_id	string	The timestamp of the revision represented as a string in the format of YYYYMMDDHHMMSS
created_by	email	The email of the user that created the revision
comment	string	The comment left by the user at the time the revision was created
targets_published	array	An array of the environment names for the publish targets used
name	string	The name given to the revision
time_created	string	A string representation of the time of creation, for example:  Tue 2017.12.13 19:54 GMT
account	string	The account name for the revision
profile	string	The profile name for the revision
checksums	object	The values in targets_published is a key factor in the checksums object. The values contain a checksums value for each JavaScript file published to that target, as shown in the following example: "targets_published" : ["dev"], "checksums" : { "dev": { "manifest.json" : "", "bundle.zip" : "", "utag.js" : "", "utag.1.js" : "" } }

Example

{
    "account": "tealium",
    "profile": "main",
    "name": "Full Release - 2017/12/13 19:53",
    "time_created": "Tue 2017.12.13 19:54 GMT",
    "checksums": {
        "prod": {
            "manifest.json": "df8bb8bdb8bc34f9d70d98ff49fdcf53e7f286520747001538b74357418178a2",
            "bundle.zip": "9309364527db38cd33538ca239929c3ed89b7b6990e99b4a41d16b50dd519e35",
            "utag.sync.js": "7cdc832b67612bb053f2e4a91ea9eab2aeb4bd26bae9668cbf5bb58bb6a2e9a1",
            "utag.js": "3c34236708b14e8fd8a82e5c363d006793fd59fc6f6a6f0367634cf245d16861",
            "utag.1.js": "9b911570ac0685a50a3a32ef780a2570b16725779b7336bdbfca2838eea6d216"
        }
    },
    "revision_id": "201712131954",
    "comment": "up to date publish",
    "created_by": "user@example.com",
    "targets_published": ["prod"]
} 

Get Revisions

You can use the GET command to returns an array of revision IDs.  The revision ID is the timestamp of the revision in the form of YYYYMMDDHHMM. This ID is used to fetch the revision details.

Use the following GET command to list revisions:

GET /v2/manifest/accounts/{account}/profiles/{profile}/revisions

Curl Request

Use the following cURL command to return a list of Revision IDs:

curl -H 'Authorization: Bearer {token}' \
https://api.tealiumiq.com/v2/manifest/accounts/{account}/profiles/{profile}/revisions

Example Response

The following example shows a typical response generated from the cURL command:

["201508181719",
 "201508181718",
 "201508181717"]

Revision IDs are listed in reverse chronological order with the newest revision listed first.

Error Messages

Potential error messages for this task are:

Error Message	Description
404 Not Found	{ "returnCode" : 1240, "message" : "Account was not found" }
	{ "returnCode" : 1250, "message" : "Profile was not found" }

Get Revision Details

Get Revision Details returns the details for the revision specified.

Use the following GET command to return details about a revision:

GET /v2/manifest/accounts/{account}/profiles/{profile}/revisions/{revision_id}/details

Curl Request

Use the following cURL command to return details for a specified Revision ID:

curl -H 'Authorization: Bearer {token}' \
https://api.tealiumiq.com/v2/manifest/accounts/{account}/profiles/{profile}/revisions/{revision_id}/details

Example Response

The following example shows a typical response generated from the cURL command:

{
    "account": "tealium",
    "profile": "profile",
    "name": "Full Release - 2016/12/13 19:53",
    "time_created": "Tue 2016.12.13 19:54 GMT",
    "checksums": {
        "prod": {
            "manifest.json": "df8bb8bdb8bc34f9d70d98ff49fdcf53e7f286520747001538b74357418178a2",
            "bundle.zip": "9309364527db38cd33538ca239929c3ed89b7b6990e99b4a41d16b50dd519e35",
            "utag.js": "3c34236708b14e8fd8a82e5c363d006793fd59fc6f6a6f0367634cf245d16861",
            "utag.1.js": "9b911570ac0685a50a3a32ef780a2570b16725779b7336bdbfca2838eea6d216",
            "utag.2.js": "0d3cbf8b3d275d181c2140c2eab88ead3c9f2002b5260d9ebd9f23cb7b60de9a"
        }
    },
    "revision_id": "201612131954",
    "comment": "up to date publish",
    "created_by": "user@example.com",
    "targets_published": ["prod"]
} 

Error Messages

Potential error messages for this task are:

Error Message	Description
404 Not Found	{ "returnCode" : 1240, "message" : "Account was not found" } { "returnCode" : 1250, "message" : "Profile was not found" } { "returnCode" : 1260, "message" : "Revision details do not exist" }

Get Revision Bundle

A revision bundle is the deployable combination of published JavaScript files for the target environment in the form of a .zip file. If a revision was published, the value from targets_published is used in this endpoint to retrieve the desired files, such as prod.

GET /v2/manifest/accounts/{account}/profiles/{profile}/revisions/{revision_id}/environments/{environment}

Curl Request

Use the following cURL command to retrieve a revision bundle .zip file:

curl -H 'Authorization: Bearer {token}' \ 
http://api.tealiumiq.com/v2/manifest/accounts/{account}/profiles/{profile}/revisions/{revision_id}/environments/{environment}

Example Response

The response for the cURL command is the return of a .zip file containing the following individual files:

File Name	Contents
utag.js	The main loader file
utag.*.js	The vendor tag files, such as utag.13.js
utag.sync.js	(Optional) Contains the synchronous loader file
mobile.html	(Optional) Contains the mobile library configuration
manifest.json	A JSON file containing the  information returned by the Revision Details endpoint The SHA256 for the bundle is not included

Error Messages

Potential error messages for this task are:

Error Message	Description
400 Not Found	{ "returnCode" : 1270, "message" : "The revision bundle requested is not the latest" }