Trigger an AWS Step Function with API Gateway

Photo by Temple Cerulean on Unsplash

This article will focus on triggering an AWS step function using the API Gateway.

To get started, please complete the steps I created in the article here https://aws.plainenglish.io/aws-typescript-cdk-and-step-functions-bbc173333aed where we set up step functions using the AWS Typescript CDK. Again, this code is not production-ready and is just available as a quick start guide.

Note: Do not perform step 13 in the previous tutorial to destroy the infrastructure as it is required for this tutorial

Step 1: Install the required constructs

In order to invoke the step function with the API Gateway — we need to install the api gateway construct.

We also need to create a role so the iam construct is required

import * as apigateway from '@aws-cdk/aws-apigateway';
import * as iam from '@aws-cdk/aws-iam';

Step 2: Setup role for API Gateway

By setting up the credentials role and attaching an inline policy that allows a StartExection of the stateMachineARN, it allows the API Gateway to trigger the lambda

// Grab the state machine arn
const stateMachineArn = this.Machine.stateMachineArn;
// Grab the role for the api gateway
const credentialsRole = new iam.Role(this, "getRole", {
  assumedBy: new iam.ServicePrincipal("apigateway.amazonaws.com"),
});
// Attach an inline policy for the statemachine arn to the credentials role
credentialsRole.attachInlinePolicy(
  new iam.Policy(this, "getPolicy", {
   statements: [
      new iam.PolicyStatement({
      actions: ["states:StartExecution"],
      effect: iam.Effect.ALLOW,
     resources: [stateMachineArn],
     }),
   ],
 })
);

Step 3: Setup API Gateway

The following line will create an api gateway as part of our infrastructure

// Create an api gateway rest api
const api = new apigateway.RestApi(this, “endpoint”);

The following lines configure the API Gateway with a demo requestTemplate for testing purposes.

// Create a method for invoking the step function via the api gateway
api.root.addMethod(“GET”,
  new apigateway.AwsIntegration({
  service: “states”,
  action: “StartExecution”,
  integrationHttpMethod: “POST”,
  options: {
   credentialsRole,
   integrationResponses: [
    {
      statusCode: “200”, 
      responseTemplates: {
        “application/json”: `{“done”: true}`,
      },
    },
   ],
   requestTemplates: {
     “application/json”: `{
      “input”: “{\\”maxNumber\\”:\\”15\\”, \\”numberToCheck\\”:\\”7\\”}”, “stateMachineArn”: “${stateMachineArn}”
  }`,
 },
 },
}),
{
 methodResponses: [{ statusCode: “200” }],
}
);

Step 4: Deploy updated environment

Run the following command to deploy the changes to your AWS account

cdk deploy

When prompted to accept the changes — enter y

The generated output will provide an endpoint for accessing the api similar to the following

Outputs:
CdkStatemachineStack.endpointEndpoint5E1E9134 = https://63n2cskxb1.execute-api.us-east-1.amazonaws.com/prod/

Step 5: Test the API Gateway and Step Function integration

Open your favorite browser and navigate to the endpoint that was outputted in the previous step

You should see results similar to the following in your browser

In the Step Function console on AWS — you should see output similar to the following under executions

Finally, if you click into the execution, the graph inspector should be simialr to the following

Step 6: Delete AWS Resources

Now that this tutorial is complete, you may want to remove the resources in order to keep your AWS account tidy.

To delete all generated AWS resources from your account, run the following command

cdk destroy

When prompted to accept that you want to delete the resources — enter y

Conclusion

This tutorial showed how to trigger an AWS Step Function using the API Gateway within AWS. You can now trigger a workflow with a GET request from within your application or wherever it may make sense

This code is not production-ready and is just an intro tutorial.

If you wish to view the code for this tutorial, it is available here:

GitHub - damogallagher/typescript-stepfunctions-cdk: Repo to show how to setup an aws step function…

More content at plainenglish.io