New Pattern: aws-apigateway-stepfunctions

[dreamorosi]

This proposed AWS Solutions Construct implements an Amazon API Gateway REST API connected to an AWS Step Function.

Use Case

Start a new workflow execution directly via HTTP request by passing the request body as input of the workflow.

Proposed Solution

The new Construct will build upon the defaults/implementations that already exist for both components.

Initializer

new ApigatewayToStepfunctions(scope: Construct, id: string, props: ApigatewayToStepfunctions Props);

Pattern Construct Props

Name	Type	Description
apiGatewayProps?	api.RestApiProps	Optional user-provided props to override the default props for the API Gateway.
allowStartExecutionOperation	boolean	Whether to deploy API Gateway Method for the StartExecution operation.
startExecutionRequestTemplate	string	Override the default API Gateway Request template for the StartExecution method, if allowStartExecutionOperation is set to true (states:StartExecution).
logGroupProps?	logs.LogGroupProps	User provided props to override the default props for for the CloudWatchLogs LogGroup.
stateMachineProps	sfn.StateMachineProps	Optional user provided props to override the default props for sfn.StateMachine
createCloudWatchAlarms	boolean	Whether to create recommended CloudWatch alarms

Pattern Properties

Name	Type	Description
apiGateway	api.RestApi	Returns an instance of the api.RestApi created by the construct.
apiGatewayRole	iam.Role	Returns an instance of the iam.Role created by the construct for API Gateway.
apiGatewayCloudWatchRole	iam.Role	Returns an instance of the iam.Role created by the construct for API Gateway for CloudWatch access.
apiGatewayLogGroup	logs.LogGroup	Returns an instance of the LogGroup created by the construct for API Gateway access logging to CloudWatch.
stateMachine	sfn.StateMachine	Returns an instance of sfn.StateMachine created by the construct
stateMachineLogGroup	logs.LogGroup	Returns an instance of the LogGroup created by the construct for StateMachine
cloudwatchAlarms?	cloudwatch.Alarm[]	Returns a list of cloudwatch.Alarm created by the construct

Sample API Usage

Method	Request Path	Request Body	Queue Action	Description
POST	/	{ "data": "Hello World!" }	states:StartExecution	Starts a new execution with the request body as input.

Default settings

Out of the box implementation of the Construct without any override will set the following defaults:

Amazon API Gateway

• Deploy an edge-optimized API endpoint
• Enable CloudWatch logging for API Gateway
• Configure least privilege access IAM role for API Gateway
• Set the default authorizationType for all API methods to IAM
• Enable X-Ray Tracing

AWS Step Function

• Enable CloudWatch logging for AWS Step Function
• Deploy best practices CloudWatch Alarms for the Step Function

Architecture

Other

Questions:

1. Given that both API Gateway & Step Functions accept a logs.LogGroupProps should this new Construct accept only one logGroupProps? or two i.e. ApiGatewaLogGroupProps? and StepFunctionLogGroupProps?? For the latter case what is the suggested naming convention?
2. According to the the allowStartExecutionOperation prop is required. Could you clarify what happens if the user sets it to false? If I understand it correctly no method is deployed, is that correct?

If the idea is welcome I am happy to implement it.

• 👋 I may be able to implement this feature request
• ⚠️ This feature might incur a breaking change

---

This is a 🚀 Feature Request

[dreamorosi]

@hnishar I see you assigned me the task & added the pattern to the roadmap. Does this mean I can start working on the implementation according to the proposed design? Or should I wait for explicit confirmation?

[hnishar]

dreamorosi@ Please wait for the confirmation, thank you!

[biffgaut]

dreamorosi@ - go ahead on everything that meets the design guidelines. Let's continue to discuss the new properties your proposing (logGroupProps and createCloudWatchAlarms) and the implications on the rest of the library - if we decide to go with them I think they can be added before submitting the PR without the overall effort for them increasing.

[biffgaut]

dreamorosi@ - your design is correct, our design guidelines doc missed these props. I will update the DESIGN_GUIDELINES.md file - you can proceed as you defined the construct above.

[diegotry]

I wonder if we should consider:

1. API Gateway HTTP APIs: they are cheaper (most customers will see an average cost saving up to 70%) and potentially faster.

2. Step Functions Synchronous Workflows: the standard execution just returns an execution ARN. Synchronous Workflows can run up to 5-minutes and can be used as an API Orchestrator

[biffgaut]

One of the tenets of our design is that Constructs are consistent - once a developer uses a construct they should be able to use other constructs intuitively. While these ideas are pretty good, we need to keep consistency in mind.

We've got API Gateway HTTP APIs in our backlog as an additional set of constructs alongside the current API Gateway constructs. We've avoided constructs that can launch different types of resources (eg - we don't pass a flag to decide whether to launch resource type A or resource type B). A second set of constructs would provide access to HTTP APIs and fit within our design tenets.

We had not considered Synchronous Workflows to this point, but at first glance it seems that a similar approach would be appropriate here.