VTL is the Velocity Template Language. I don't love VTL. Unfortunately, AWS does love VTL. Probably because they love Java. They love Java (and don't like Oracle) so much they made their own. VTL is very Java.

As someone who doesn't have a Java background, I've struggled to find resources to help wrangle VTL. And When you start trying to master it, you run across posts like this on StackOverflow that don't spark joy ✨

Some of the serverless services that I use and love on AWS use VTL heavily, mainly API Gateway and AppSync. The VTL project is owned by the Apache Foundation, and so has a reasonable amount of documentation. The most useful links are the VTL Reference and the User Guide which are worth your attention.

For AppSync and Amplify use-cases the Resolver Mapping Template reference is key, as it details the helpers available to you, and the various service-specific (e.g. DynamoDB, Lambda, etc) template requirements. In particular, go through the Programming Guide in detail.

There's also a similar page for API Gateway called data transformation for REST APIs. If you're using the Amplify CLI, you can run your resolvers locally which helps validate your templates.

As I don't usually use the Amplify CLI my workflow is a little more blunt, but still effective: I open the resolver/response template in the console so that I can quickly edit it and hit my deployed endpoint. Editing and saving a template is relatively quick, and much quicker than re-deploying an API:

Editing VTL templates for AppSync on the fly

While I don't love VTL, it has some nice features that I appreciate: it encourages separation of business and display logic, it prevents you from doing crazy/unbounded things in your template, and as a worst-case it just complain loudly without breaking anything.

Got anything else that helped you learn VTL quickly? Share it with me on Twitter please!


Photo by emarts emarts on Unsplash