API update: Template names switch to url-safe slugs

We'd like to share a change to our API that we'll be making on April 30, 2020. On that day, we will change all the names that our customers have given to their Templates to a format that is URL-safe. If, for instance, your Template was previously called Video encode for Apple Devices, the new name will be video-encode-for-apple-devices.

This change will make it possible to start referring to Templates by this URL-safe name, which we call a slug. As a result, you will be able to create your Assemblies like this:

{
  "params": {
    "template_id": "video-encode-for-apple-devices"
  }
}

instead of only by their ID, like before:

{
  "params": {
    "template_id": "a528022861cf4a0292ea96bd2b18efc1"
  }
}

This makes Assembly Instructions more self-explanatory right inside your code editor, and it can help avoid mistakes that are easily overlooked when using UUIDv4 without dashes like a528022861cf4a0292ea96bd2b18efc1. We also have a, still secret, feature in the making that will benefit greatly from being able to refer to Templates by their slug. Stay tuned!

Of course, as with any change, there is a trade-off: if you start adopting Template slugs, it does mean that you cannot change that name (read: slug) without breaking your integrations. This should either be done carefully, or – if this is problematic for your usecase – just continue referring to Template IDs as you already do. No changes needed.

Is converting names to slugs backwards compatible?

We do not expect any breakage from the migration since, until that point, the human-readable Template names (Video encode for Apple Devices) should have only been used by, well, humans. Transloadit does not offer any functionality based on these names, besides displaying them in lists and letting humans search on them. This will continue to work after the migration. Type: apple, and you'll get video-encode-for-apple-devices, just like you would have gotten Video encode for Apple Devices in your search results.

The only thing that could break is if, in your own automation code, you are relying on Template names somehow. If this is the case for you, we recommend changing this before April 30, 2020 to avoid any breakage. Best not rely on names at all, and use IDs in your own code instead if you want to ensure things will work forever.