Mapping AWS State Machine output to API Gateway response with VTL

This is sort of a continuation back to the previous article I wrote regarding zero code workflows creating Cognito users with Step Functions

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

Is Failure really Success?

One thing that I wanted to be able to do is have the 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

Success is show below

And now the failure

So 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": "sample@user.com",
      "userId": "1000125"
    }
  }
}

As you can see, it’s a pretty full object that has the input supplied from the API Gateway request and 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
  }
}

What do I do with that?

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

• API Gateway Data Mapping
• Mapping Variables and Functions
• Overrides
• VTL (Velocity Template Language)

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')))

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 too and when it’s successfully I just return the output about the user

#if($parsedPayload.response.statusCode == 400)
#set($context.responseOverride.status = 400)
{
    "message": "$parsedPayload.response.message"
}
#else
{
    "firstName": "$parsedPayload.response.body.firstName",
    "lastName": "$parsedPayload.response.body.lastName",
    "emailAddress": "$parsedPayload.response.body.emailAddress",
    "userId": "$parsedPayload.response.body.userId"
}
#end

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.

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