AWS CDK: API Gateway Service Integration for Step Functions

December 7th, 2020 380 Words

Most people only use Amazon API Gateway as an HTTP interface to invoke AWS Lambda functions. But, the service has way more to offer. For example, you can easily create an HTTP interface for nearly any AWS Service; not only AWS Lambda. Based on the previous post, on how to create a State Machine with AWS Step Functions and AWS Cloud Development Kit, this post describes how to create an HTTP interface to start an execution of a State Machine using the AWS CDK.

AWS Step Functions

With AWS Step Functions, you can easily orchestrate serverless functions and sequence them with other AWS services to a bundle application. You can create AWS Step Functions with CloudFormation, the AWS Cloud Development Kit, or - of course - using the visual interface available in the AWS Management Console.

The AWS Cloud Development Kit simplifies a couple of things. For AWS Step Functions, the CDK offers a few helper functions to easily configure individual steps. Head over to State Machine with AWS Step Functions and AWS Cloud Development Kit to see an example. This post assumes you have a State Machine already deployed and can access the Arn like this:

const statemachine = new StateMachine(this, "Machine");

new StateMachineTrigger(this, "Trigger", {
  stateMachineArn: statemachine.Machine.stateMachineArn,

API Gateway Service Integration

The Amazon API Gateway is perfect to create an HTTP interface for triggering API actions. But first, let’s start with the needed IAM Role for starting an execution in AWS Step Functions:

const credentialsRole = new iam.Role(this, "getRole", {
  assumedBy: new iam.ServicePrincipal(""),

  new iam.Policy(this, "getPolicy", {
    statements: [
      new iam.PolicyStatement({
        actions: ["states:StartExecution"],
        effect: iam.Effect.ALLOW,
        resources: [props.stateMachineArn],

Using this IAM Role, you can create an API Gateway Rest API to execute the needed API call for HTTP requests on a specific URL using a specified HTTP method:

const api = new apigateway.RestApi(this, "endpoint");

  new apigateway.AwsIntegration({
    service: "states",
    action: "StartExecution",
    integrationHttpMethod: "POST",
    options: {
      integrationResponses: [
          statusCode: "200",
          responseTemplates: {
            "application/json": `{"done": true}`,
      requestTemplates: {
        "application/json": `{
              "input": "{\\"prefix\\":\\"prod\\"}",
              "stateMachineArn": "${props.stateMachineArn}"
    methodResponses: [{ statusCode: "200" }],

After deploying this CloudFormation stack, you can use cURL to start your configured AWS Step Functions.

$ > curl

{"done": true}