iQ Revisions (v1 API)

iQ Revisions (v1 API)

by Community Manager on ‎02-15-2018 03:46 PM - edited on ‎02-20-2018 02:37 PM by Community Manager (132 Views)

A revision is a saved version of your iQ profile. A new revision is created each time a "Save as..." is performed. Then as each version is updated and/or published, the status is reflected in the revision. The revision status contains information about the version, such as published environments, user comments, timestamps, and checksums for the generated JavaScript files.

A revision bundle is a zip file containing the published files related to the revision.

Before You Begin: The iQ revisions API must be activated before it will return data. Contact your account manager to activate this endpoint.

In this article:

Table of Contents Placeholder 

Revision Fields

Revisions are returned as JSON objects containing the following fields:

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.
targets_published array Array of environment names of the publish targets used.
name string The name given to the revision.
time_created string A string representation of the time of creation eg. "Tue 2016.12.13 19:54 GMT"
account string The account name of the revision.
profile string The profile name of the revision.
checksums object

Each value in targets_published wil be key in this object, the value of which is an object containing a checksum value for each JavaScript file published to that target.

Example:

"targets_published" : ["dev"],
"checksums" : {
"dev": {
"manifest.json" : "<CHECKSUM HERE>",
"bundle.zip" : "<CHECKSUM HERE>",
"utag.js" : "<CHECKSUM HERE>",
"utag.1.js" : "<CHECKSUM HERE>"
}
}

Example Revision:

{
    "account": "tealium",
    "profile": "main",
    "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.sync.js": "7cdc832b67612bb053f2e4a91ea9eab2aeb4bd26bae9668cbf5bb58bb6a2e9a1",
            "utag.js": "3c34236708b14e8fd8a82e5c363d006793fd59fc6f6a6f0367634cf245d16861",
            "utag.1.js": "9b911570ac0685a50a3a32ef780a2570b16725779b7336bdbfca2838eea6d216"
        }
    },
    "revision_id": "201612131954",
    "comment": "up to date publish",
    "created_by": "user@example.com",
    "targets_published": ["prod"]
} 

List Revisions

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.

GET /v1/accounts/{account}/{profile}/revisions

Curl Request

curl -b JSESSIONID={session_id} \
  https://api.tealiumiq.com/v1/accounts/{account}/{profile}/revisions?utk={token}

Example Response

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

The revision ID's are listed in reverse chronological order ie. the newest revision first.

Error Messages

400 NOT FOUND

{ 
   "returnCode" : 1240,
   "message" : "Account was not found" 
}

 

{ 
   "returnCode" : 1250,
   "message" : "Profile was not found" 
}

Get Revision Details

Returns the revision details.

GET /v1/accounts/{account}/{profile}/revisions/{revision_id}/details

Curl Request

curl -i -b JSESSIONID={session_id} \ 
  https://api.tealiumiq.com/v1/accounts/{account}/{profile}/revisions/{revision_id}/details?utk={token}

Example Response

{
    "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

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 corpus of the published JavaScript files for the target environment in the form of a zip file. If a revision was published, the value from "targets_published" will be used in this enpoint to retrieve the desired files eg. "prod".

GET/v1/accounts/{account}/{profile}/revisions/{revision_id}/{target} 

Curl Request

curl -b JSESSION={session_id} \
  http://api.tealiumiq.com/v1/accounts/{account}/{profile}/revisions/{revision_id}/{target}?utk={token} \ 
  -o utag.zip
 

Response

The request returns a ".zip" file that contains:

  • utag.js - the main loader file
  • utag.*.js - the vendor tag files eg. utag.13.js
  • utag.sync.js - (optional) the synchronous loader file
  • mobile.html - (optional) mobile library configuration
  • manifest.json - this json file contains the same information returned by the Revision Details endpoint minus the SHA256 of the bundle. 

Error Messages

400 NOT FOUND

{ 
   "returnCode" : 1270,
   "message" : "The revision bundle requested is not the latest" 
}