Google Tag Manager<\/a> has a very nifty programmatic API<\/a> that lets you do almost anything that\u2019s also possible within the GTM UI. I\u2019ve used the API a lot, most notably for my GTM Tools<\/a>, which might be getting a new release soon, too!<\/p>\n The API was recently updated to its second release version<\/a> (V2), and in this article I want to go over the additions, removals, and changes that the new version introduced.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n First of all, V1 of the API<\/a> is still fully functional, so you don\u2019t have to migrate until you\u2019re ready. That being said, the new version brings about a number of changes I\u2019m sure you\u2019ll find helpful when working with the API.<\/p>\n \n \n Subscribe to the Simmer newsletter<\/a> to get the latest news and content from Simo Ahava into your email inbox!\n <\/p>\n <\/span><\/p>\n The most significant change, in my opinion, is the introduction of workspace<\/strong><\/a> as the central focus in almost all interactions with anything on the container level. It\u2019s not just that there\u2019s a new namespace for workspaces in the API, but that you must always reference a workspace when interacting with container assets. This is going to be the biggest hurdle in a migration, I believe. Anything that happens in a workspace (pretty much all UI interactions with a single container draft) must now be accompanied by the workspace ID of the workspace you want to modify. This, in turn, means a round trip via the workspaces API<\/a> to get the IDs you need.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Another very visible change is the separation of Built-in Variables<\/strong> into its own namespace<\/a>. Luckily there\u2019s also a simple batching shorthand for enabling \/ deleting multiple Built-in Variables in a single request.<\/p>\n On a technical level, when using client libraries you now provide the path to the asset as a single parameter (basically Finally, and I love this, there\u2019s support for adding notes<\/strong> to pretty much any resource available via the API. Even though the UI doesn\u2019t yet support the notes<\/strong> field as widely, you can now add descriptive text to all assets via the API. Very useful for documenting the container.<\/p>\n (UPDATE<\/strong>: a short while after writing this article, GTM released support for notes in the UI<\/a> too, yay!)<\/p>\n What follows is a walkthrough of all the namespaces in the new version of the API, with information on what changed from V1.<\/p>\n Resource changes:<\/strong> The Accounts resource<\/a> has the following new<\/strong> fields:<\/p>\n Method changes:<\/strong> There are no significant changes in Accounts methods.<\/p>\n This is a completely new namespace in the API. Instead of passing a list of Built-in Variables in the container resource itself, you now need to explicitly enable Built-in Variables in the workspace of your choice. You can read the full description of this new feature here<\/a>.<\/p>\n Note that if you want to enable multiple Built-in Variables in a single request (strongly recommended), you can use a shorthand batch format to do so.<\/p>\n Resource changes:<\/strong> The Containers<\/a> namespace hasn\u2019t changed that much. The new<\/strong> fields are the same as with Accounts: Method changes:<\/strong> There are no significant changes to the Containers methods.<\/p>\n Resource changes:<\/strong> The main changes to the Environments<\/a> resource are the following:<\/p>\n Method changes<\/strong>: The most significant change is that the old Resource changes:<\/strong> The big changes to the Folders<\/a> resource are:<\/p>\n Method changes:<\/strong> The main changes to the methods are that both There\u2019s also a new method, Resource changes:<\/strong> The only changes are the inclusion of Method changes:<\/strong> The only big change is the introduction of the Triggers was affected in exactly the same way as Tags. The changes are identical, with the exception of (Note, this used to be called just Permissions<\/a> in the previous API version documentation.) Method changes:<\/strong> No significant changes to methods.<\/p>\n Changes to Variables<\/a> are pretty much on par with what\u2019s done to Tags, so check the relevant section above for more details.<\/p>\n The Version Headers<\/a> API is a new addition to the GTM API. Basically, it\u2019s a shorthand for accessing versions of any given container. Unlike the Versions API itself, Version Headers only returns, surprise surprise, headers. This keeps the API calls really lean, and lets you quickly get the necessary information, such as the version ID.<\/p>\n You can check the documentation for more details on the resource representation<\/a>.<\/p>\n The API has two methods.<\/p>\n (Note, this used to be called Container Versions<\/a> in the previous API version documentation.) Note that the Method changes<\/strong>: Here are the main changes to Versions methods:<\/p>\n The Workspaces API<\/strong> was introduced in V2 of the GTM API. You will definitely want to follow this link<\/a> and familiarize yourself with the new API. Understanding how workspaces function in the container<\/a> is integral to understanding how the GTM API works.<\/p>\n Workspaces are fundamental to many interactions with the API. Basically, when you work with tags, triggers, variables, folders, and built-in variables, you always need to provide the workspace ID with which you are interacting. There\u2019s no single \u201cContainer draft\u201d anymore. There\u2019s always a workspace you\u2019re working in.<\/p>\n In addition to having to update your methods, this also means that you need to rethink some of the API flows you have been using thus far. For example, instead of just creating new items in a container, you now need to specify the workspace you want to work with. This means you might first need to The new API certainly has a lot of stuff to wrap your head around. The introduction of workspaces, for one, is certain to make migration a bit of a headache. However, it would be equally awkward to work with an API that isn\u2019t in sync with the feature set of the UI it is managing. For this reason, I think it makes a lot of sense to upgrade to the latest API version as soon as possible.<\/p>\n Most of the stuff is easy to figure out, such as how to move from One thing that\u2019s a constant feature request from me is that Google would update their error messages. It\u2019s very difficult to understand what\u2019s wrong when all you see in the logs is \u201c400 Bad Request\u201d or \u201c500 Backend Error\u201d.<\/p>\n What do you think about the new API? Have you written tools for the GTM API you want to share? Please do!<\/p>\n<\/p><\/div>\n![\"Google](\"https:\/\/www.simoahava.com\/images\/2017\/03\/gtm-api-v2.jpg#ZgotmplZ\")
<\/p>\n
\n X<\/span><\/p>\n
\n The Simmer Newsletter<\/strong>\n <\/p>\nBiggest changes<\/h2>\n
![\"Workspaces](\"https:\/\/www.simoahava.com\/images\/2017\/03\/gtm-api-workspaces.jpg#ZgotmplZ\")
<\/p>\npath<\/code> or parent<\/code>) instead of using multiple named parameters. The new resource representations include the path<\/code> key, which you can then use to easily chain API commands together.<\/p>\nDetailed changes<\/h2>\n
1. Accounts<\/h3>\n
\n
path<\/code>: path of the Account, e.g. accounts\/12345<\/code><\/li>\ntagManagerUrl<\/code>: direct URL to your account in the GTM API<\/li>\n<\/ul>\n2. Built-in Variables<\/h3>\n
accounts()\n .containers()\n .workspaces()\n .built_in_variables()\n .create(\n parent='accounts\/<\/span>%s<\/span>\/containers\/<\/span>%s<\/span>\/workspaces\/<\/span>%s<\/span>'<\/span> % (accountId, containerId, workspaceId),\n type<\/span>=['clickClasses'<\/span>, 'clickElement'<\/span>, 'clickId'<\/span>, 'clickUrl'<\/span>, 'clickText'<\/span>, 'clickTarget'<\/span>] )<\/code><\/pre>\n<\/div>\n3. Containers<\/h3>\n
path<\/code> and tagManagerUrl<\/code>. Fields that were removed<\/strong> from V2 are the redundant timeZoneCountryId<\/code> and timeZoneId<\/code>. The enabledBuiltInVariable<\/code> field has been replaced by the Built-in Variables namespace introduced above.<\/p>\n4. Environments<\/h3>\n
\n
path<\/code>: relative path in the API to the given environment<\/p>\n<\/li>\nauthorizationTimestamp<\/code>: supports both nanos<\/code> and seconds<\/code> as values<\/p>\n<\/li>\nworkspaceId<\/code>: link to preview a given workspace in the environment<\/p>\n<\/li>\ntagManagerUrl<\/code>: link to the Environments page in the container<\/p>\n<\/li>\n<\/ul>\nenvironments.reauthorize_environments<\/code> namespace has been removed in favor of simply adding a reauthorize()<\/code><\/a> method to the main Environments API.<\/p>\n5. Folders<\/h3>\n
\n
path<\/code>: relative API path to the folder<\/p>\n<\/li>\nworkspaceId<\/code>: ID of the workspace from which the folder was fetched<\/p>\n<\/li>\ntagManagerUrl<\/code>: link to the folder in the GTM UI<\/p>\n<\/li>\nnotes<\/code>: notes about the folder<\/p>\n<\/li>\n<\/ul>\nfolders.entities<\/code> and folders.move_folders<\/code> have been replaced with their own dedicated API methods in entities()<\/code><\/a> and move_entities_to_folders()<\/code><\/a>, respectively.<\/p>\nrevert()<\/code><\/a>, which lets you revert changes to a folder in the given workspace.<\/p>\n6. Tags<\/h3>\n
path<\/code>, workspaceId<\/code> and tagManagerUrl<\/code>. Otherwise the resource representation has remained relatively unchanged.<\/p>\nrevert()<\/code><\/a> method, which lets you cancel any changes to the tag in the given workspace.<\/p>\n7. Triggers<\/h3>\n
notes<\/code> now introduced as a writable field for Triggers, too.<\/p>\n8. User Permissions<\/h3>\n
\nResource changes:<\/strong> The main changes to User Permissions<\/a> are:<\/p>\n\n
path<\/code>: relative API path to the permission entity, includes the permissionId<\/code><\/p>\n<\/li>\naccountAccess.permission<\/code>: now a string rather than a list\/array<\/p>\n<\/li>\ncontainerAccess[].permission<\/code>: now a string rather than a list\/array<\/p>\n<\/li>\n<\/ul>\n8. Variables<\/h3>\n
\n
latest()<\/code> returns the version header of the Latest Container Version. The Latest version is the most recently created version in Google Tag Manager, and is very relevant to Workspaces, since Workspaces need to be synchronized with the Latest container version before they can be published or turned into versions themselves.<\/p>\n<\/li>\nlist()<\/code> returns a list of all container versions in any given container.<\/p>\n<\/li>\n<\/ul>\n10. Versions<\/h3>\n
\nResource changes:<\/strong> Here are the changes to Versions<\/a> in the GTM API:<\/p>\n\n
path<\/code>: relative API path to the container version<\/p>\n<\/li>\ndescription<\/code>: used to be called notes<\/code> in the previous API version<\/p>\n<\/li>\nbuiltInVariable<\/code>: list of Built-in Variables enabled in the version<\/p>\n<\/li>\ntagManagerUrl<\/code>: link to the container version in the GTM UI<\/p>\n<\/li>\n<\/ul>\nmacro<\/code> and rule<\/code> parameters have been deprecated in the new API version.<\/p>\n\n
create()<\/code>: deprecated<\/strong> – container version creation is done via Workspaces<\/p>\n<\/li>\nlist()<\/code>: deprecated<\/strong> – version list is now done via Version Headers<\/p>\n<\/li>\nlive()<\/code>: retrieves the container version that is currently live in the container<\/p>\n<\/li>\nset_latest()<\/code>: sets the given version as the Latest version in the container – replaces restore()<\/code><\/a> in the previous API version<\/p>\n<\/li>\n<\/ul>\n11. Workspaces<\/h3>\n
\n
create_version()<\/code> creates a version out of a workspace but only if the version passes all GTM\u2019s syntax and validation checks.<\/p>\n<\/li>\ngetStatus()<\/code> returns all the conflicting and\/or modified entities in the workspace. This is useful if you want to check if the workspace is ready to be turned into a version.<\/p>\n<\/li>\nresolve_conflict()<\/code> lets you resolve conflicts in favor of the workspace or the latest version.<\/p>\n<\/li>\nsync()<\/code> lets you synchronize the workspace with the latest container version – a necessary step to take before creating the version.<\/p>\n<\/li>\n<\/ul>\nlist()<\/code><\/a> the available workspaces to get the ID you are looking for. Or perhaps you want to create()<\/code><\/a> a new workspace so that you don\u2019t mess with other people\u2019s unfinished work.<\/p>\nSummary<\/h2>\n
accountId=<\/code> and containerId=<\/code> to path=accounts\/accountId\/containers\/containerId<\/code>. In fact, I think changes like this make it easier to work with programming languages that make use of string interpolation (Python, for example). There are some conventions that might take time to understand routinely, such as how to use versionheaders.list<\/code> instead of versions.list<\/code>.<\/p>\n