DEV Community

Cover image for Mapping AWS State Machine output to API Gateway response with VTL
Benjamen Pyle for AWS Community Builders

Posted on • Originally published at

Mapping AWS State Machine output to API Gateway response with VTL

This is a continuation of a previous article I wrote regarding zero code workflows creating Cognito users with Step Functions. Part of using State Machines with API Gateway is dealing with the response and potential VTL mapping.

The goals of this article are to document some of the tips and things that I picked up along the way.

Is Failure Success?

I wanted to be able to have a state machine indicate that it processed successfully regardless of whether the Cognito user was created or it had to be rolled back. I made the decision both of those warranted a clean run of the state machine since it was being executed via API Gateway. But where I got stuck was how to return back to the client/caller that the workflow actually did fail and that the input was bad and that a status code of 400 BAD REQUEST was appropriate. This is where API Gateway VTL Mapping with State Machine responses really comes into play.

Success is shown below

Cognito user creation step function state machineSuccess Flow

And now the failure

State machine failureSo my concern now becomes, how do I let the client know

Outputs from the State Machine

First off on the success, I’m returning the output like this

  "response": {
    "statusCode": 200,
    "body": {
      "firstName": "Sample",
      "lastName": "User",
      "emailAddress": "",
      "userId": "1000125"
Enter fullscreen mode Exit fullscreen mode

As you can see, it’s a pretty full object that has the input supplied from the API Gateway request. Additionally, it contains what I really want which is the auto-generated User ID. I’m going to use that in my client

Second, the failure

  "response": {
    "message": "error creating user",
    "statusCode": 400
Enter fullscreen mode Exit fullscreen mode

API Gateway VTL Mapping State Machine Response?

With API Gateway you have the option to do incoming request mapping as well as outgoing response mapping. Articles I learned from when working on this

The raw output from my State Machine actually has quite a bit more details about the execution such as billing time, execution id, inputs and outputs. For this
example I’m interested in outputs but you could also use the execution id for debugging and tracing

With VTL I can select out the output like this

#set ($parsedPayload = $util.parseJson($input.path('$.output')))
Enter fullscreen mode Exit fullscreen mode

Now I’ve got a variable called $parsedPayload which holds a JSON object that I can query via JSONPath

Through that mechanism combined with VTL I’m going to override the response status code to 400 BAD REQUEST when the state machine tells me to and when it’s successful I just return the output about the user

#if($parsedPayload.response.statusCode == 400)
#set($context.responseOverride.status = 400)
    "message": "$parsedPayload.response.message"
    "firstName": "$parsedPayload.response.body.firstName",
    "lastName": "$parsedPayload.response.body.lastName",
    "emailAddress": "$parsedPayload.response.body.emailAddress",
    "userId": "$parsedPayload.response.body.userId"
Enter fullscreen mode Exit fullscreen mode

Wrap Up

Continuing with the theme of pushing code and behavior into the infrastructure puts the ownership of operation on the Cloud Provider. In this case, AWS. By doing this, I only spend time writing code that I HAVE to write and spend less time worrying/managing the code/operations that AWS can run for me. Using API Gateway’s VTL Mapping with State Machine responses helps achieve just that.

By using Step Functions, Intrinsic Functions, API Gateway with VTL and JSONPath you get a highly scalable and robust solution without having to write code

Top comments (0)