feat(stepfunctions-tasks): Support calling ApiGateway REST and HTTP APIs

packages/@aws-cdk/aws-stepfunctions-tasks/README.md

@@ -28,6 +28,9 @@ This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aw
   - [ResultPath](#resultpath)
 - [Parameters](#task-parameters-from-the-state-json)
 - [Evaluate Expression](#evaluate-expression)
+- [API Gateway](#api-gateway)
+  - [Call REST API Endpoint](#call-rest-api-endpoint)
+  - [Call HTTP API Endpoint](#call-http-api-endpoint)
 - [Athena](#athena)
   - [StartQueryExecution](#startQueryExecution)
   - [GetQueryExecution](#getQueryExecution)
@@ -217,6 +220,47 @@ The `EvaluateExpression` supports a `runtime` prop to specify the Lambda
 runtime to use to evaluate the expression. Currently, only runtimes
 of the Node.js family are supported.
 
+## API Gateway
+
+Step Functions supports [API Gateway](https://docs.aws.amazon.com/step-functions/latest/dg/connect-api-gateway.html) through the service integration pattern.
+
+HTTP APIs are designed for low-latency, cost-effective integrations with AWS services, including AWS Lambda, and HTTP endpoints. 
+HTTP APIs support OIDC and OAuth 2.0 authorization, and come with built-in support for CORS and automatic deployments. 
+Previous-generation REST APIs currently offer more features. More details can be found [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html).
+
+### Call REST API Endpoint
+
+The `CallApiGatewayRestApiEndpoint` calls the REST API endpoint.
+
+```ts
+import * as sfn from '@aws-cdk/aws-stepfunctions';
+import * as tasks from `@aws-cdk/aws-stepfunctions-tasks`;
+
+const restApi = new apigateway.RestApi(stack, 'MyRestApi');
+
+const invokeTask = new tasks.CallApiGatewayRestApiEndpoint(stack, 'Call REST API', {
+  api: restApi,
+  stageName: 'prod',
+  method: HttpMethod.GET,
+});
+```
+
+### Call HTTP API Endpoint
+
+The `CallApiGatewayHttpApiEndpoint` calls the HTTP API endpoint.
+
+```ts
+import * as sfn from '@aws-cdk/aws-stepfunctions';
+import * as tasks from `@aws-cdk/aws-stepfunctions-tasks`;
+
+const httpApi = new apigatewayv2.HttpApi(stack, 'MyHttpApi');
+
+const invokeTask = new tasks.CallApiGatewayHttpApiEndpoint(stack, 'Call HTTP API', {
+  api: httpApi,
+  method: HttpMethod.GET,
+});
+```
+
 ## Athena
 
 Step Functions supports [Athena](https://docs.aws.amazon.com/step-functions/latest/dg/connect-athena.html) through the service integration pattern.

packages/@aws-cdk/aws-stepfunctions-tasks/lib/apigateway/base-types.ts

@@ -0,0 +1,79 @@
+import * as sfn from '@aws-cdk/aws-stepfunctions';
+
+/** Http Methods that API Gateway supports */
+export enum HttpMethod {
+  /** Retreive data from a server at the specified resource */
+  GET = 'GET',
+
+  /** Send data to the API endpoint to create or udpate a resource */
+  POST = 'POST',
+
+  /** Send data to the API endpoint to update or create a resource */
+  PUT = 'PUT',
+
+  /** Delete the resource at the specified endpoint */
+  DELETE = 'DELETE',
+
+  /** Apply partial modifications to the resource */
+  PATCH = 'PATCH',
+
+  /** Retreive data from a server at the specified resource without the response body */
+  HEAD = 'HEAD',
+
+  /** Return data describing what other methods and operations the server supports */
+  OPTIONS = 'OPTIONS'
+}
+
+/**
+ * The authentication method used to call the endpoint
+ */
+export enum AuthType {
+  /** Call the API direclty with no authorization method */
+  NO_AUTH = 'NO_AUTH',
+
+  /** Use the IAM role associated with the current state machine for authorization */
+  IAM_ROLE = 'IAM_ROLE',
+
+  /** Use the resource policy of the API for authorization */
+  RESOURCE_POLICY = 'RESOURCE_POLICY',
+}
+
+/**
+ * Base CallApiGatewayEdnpoint Task Props
+ */
+export interface CallApiGatewayEndpointBaseProps extends sfn.TaskStateBaseProps {
+  /**
+   * Http method for the API
+   */
+  readonly method: HttpMethod;
+
+  /**
+   * HTTP request information that does not relate to contents of the request
+   * @default - No headers
+   */
+  readonly headers?: sfn.TaskInput;
+
+  /**
+   * Path parameters appended after API endpoint
+   * @default - No path
+   */
+  readonly apiPath?: string;
+
+  /**
+   * Query strings attatched to end of request
+   * @default - No query parameters
+   */
+  readonly queryParameters?: sfn.TaskInput;
+
+  /**
+   * HTTP Request body
+   * @default - No request body
+   */
+  readonly requestBody?: sfn.TaskInput;
+
+  /**
+   * Authentication methods
+   * @default AuthType.NO_AUTH
+   */
+  readonly authType?: AuthType;
+}

packages/@aws-cdk/aws-stepfunctions-tasks/lib/apigateway/base.ts

@@ -0,0 +1,69 @@
+import * as iam from '@aws-cdk/aws-iam';
+import * as sfn from '@aws-cdk/aws-stepfunctions';
+import { Construct } from 'constructs';
+import { integrationResourceArn, validatePatternSupported } from '../private/task-utils';
+import { AuthType, CallApiGatewayEndpointBaseProps } from './base-types';
+
+/**
+ * Base CallApiGatewayEndpoint Task
+ * @internal
+ */
+export abstract class CallApiGatewayEndpointBase extends sfn.TaskStateBase {
+  private static readonly SUPPORTED_INTEGRATION_PATTERNS: sfn.IntegrationPattern[] = [
+    sfn.IntegrationPattern.REQUEST_RESPONSE,
+    sfn.IntegrationPattern.WAIT_FOR_TASK_TOKEN,
+  ];
+
+  private readonly baseProps: CallApiGatewayEndpointBaseProps;
+  private readonly integrationPattern: sfn.IntegrationPattern;
+
+  protected abstract readonly apiEndpoint: string;
+  protected abstract readonly arnForExecuteApi: string;
+  protected abstract readonly stageName?: string;
+
+  constructor(scope: Construct, id: string, props: CallApiGatewayEndpointBaseProps) {
+    super(scope, id, props);
+
+    this.baseProps = props;
+    this.integrationPattern = props.integrationPattern ?? sfn.IntegrationPattern.REQUEST_RESPONSE;
+    validatePatternSupported(this.integrationPattern, CallApiGatewayEndpointBase.SUPPORTED_INTEGRATION_PATTERNS);
+
+    if (this.integrationPattern === sfn.IntegrationPattern.WAIT_FOR_TASK_TOKEN) {
+      if (!sfn.FieldUtils.containsTaskToken(this.baseProps.headers)) {
+        throw new Error('Task Token is required in `headers` for WAIT_FOR_TASK_TOKEN pattern. Use JsonPath.taskToken to set the token.');
+      }
+    }
+  }
+
+  /**
+   * @internal
+   */
+  protected _renderTask() {
+    return {
+      Resource: integrationResourceArn('apigateway', 'invoke', this.integrationPattern),
+      Parameters: sfn.FieldUtils.renderObject({
+        ApiEndpoint: this.apiEndpoint,
+        Method: this.baseProps.method,
+        Headers: this.baseProps.headers?.value,
+        Stage: this.stageName,
+        Path: this.baseProps.apiPath,
+        QueryParameters: this.baseProps.queryParameters?.value,
+        RequestBody: this.baseProps.requestBody?.value,
+        AuthType: this.baseProps.authType ? this.baseProps.authType : 'NO_AUTH',
+      }),
+    };
+  }
+
+  protected createPolicyStatements(): iam.PolicyStatement[] {
+    if (this.baseProps.authType === AuthType.NO_AUTH) {
+      return [];
+    }
+
+    return [
+      new iam.PolicyStatement({
+        resources: [this.arnForExecuteApi],
+        actions: ['execute-api:Invoke'],
+      }),
+    ];
+  }
+}

packages/@aws-cdk/aws-stepfunctions-tasks/lib/apigateway/call-http-api.ts

@@ -0,0 +1,62 @@
+import * as apigatewayv2 from '@aws-cdk/aws-apigatewayv2';
+import * as iam from '@aws-cdk/aws-iam';
+import * as sfn from '@aws-cdk/aws-stepfunctions';
+import * as cdk from '@aws-cdk/core';
+import { Construct } from 'constructs';
+import { CallApiGatewayEndpointBase } from './base';
+import { CallApiGatewayEndpointBaseProps } from './base-types';
+
+/**
+ * Properties for calling an HTTP API Endpoint
+ */
+export interface CallApiGatewayHttpApiEndpointProps extends CallApiGatewayEndpointBaseProps {
+  /**
+   * API to call
+   */
+  readonly api: apigatewayv2.IHttpApi;
+
+  /**
+   * Name of the stage where the API is deployed to in API Gateway
+   * @default '$default'
+   */
+  readonly stageName?: string;
+}
+
+/**
+ * Call HTTP API endpoint as a Task
+ *
+ * @see https://docs.aws.amazon.com/step-functions/latest/dg/connect-api-gateway.html
+ */
+export class CallApiGatewayHttpApiEndpoint extends CallApiGatewayEndpointBase {
+  protected readonly taskMetrics?: sfn.TaskMetricsConfig | undefined;
+  protected readonly taskPolicies?: iam.PolicyStatement[] | undefined;
+
+  protected readonly apiEndpoint: string;
+  protected readonly arnForExecuteApi: string;
+  protected readonly stageName?: string;
+
+  constructor(scope: Construct, id: string, private readonly props: CallApiGatewayHttpApiEndpointProps) {
+    super(scope, id, props);
+
+    this.apiEndpoint = this.getApiEndpoint();
+    this.arnForExecuteApi = this.getArnForExecuteApi();
+
+    this.taskPolicies = this.createPolicyStatements();
+  }
+
+  private getApiEndpoint(): string {
+    const apiStack = cdk.Stack.of(this.props.api);
+    return `${this.props.api.apiId}.execute-api.${apiStack.region}.${apiStack.urlSuffix}`;
+  }
+
+  private getArnForExecuteApi(): string {
+    const { api, stageName, method, apiPath } = this.props;
+
+    return cdk.Stack.of(api).formatArn({
+      service: 'execute-api',
+      resource: api.apiId,
+      sep: '/',
+      resourceName: `${stageName}/${method}${apiPath}`,
+    });
+  }
+}

packages/@aws-cdk/aws-stepfunctions-tasks/lib/apigateway/call-rest-api.ts

@@ -0,0 +1,51 @@
+import * as apigateway from '@aws-cdk/aws-apigateway';
+import * as iam from '@aws-cdk/aws-iam';
+import * as sfn from '@aws-cdk/aws-stepfunctions';
+import * as cdk from '@aws-cdk/core';
+import { Construct } from 'constructs';
+import { CallApiGatewayEndpointBase } from './base';
+import { CallApiGatewayEndpointBaseProps } from './base-types';
+
+/**
+ * Properties for calling an REST API Endpoint
+ */
+export interface CallApiGatewayRestApiEndpointProps extends CallApiGatewayEndpointBaseProps {
+  /**
+   * API to call
+   */
+  readonly api: apigateway.IRestApi;
+
+  /**
+   * Name of the stage where the API is deployed to in API Gateway
+   */
+  readonly stageName: string;
+}
+
+/**
+ * Call REST API endpoint as a Task
+ *
+ * @see https://docs.aws.amazon.com/step-functions/latest/dg/connect-api-gateway.html
+ */
+export class CallApiGatewayRestApiEndpoint extends CallApiGatewayEndpointBase {
+  protected readonly taskMetrics?: sfn.TaskMetricsConfig | undefined;
+  protected readonly taskPolicies?: iam.PolicyStatement[] | undefined;
+
+  protected readonly apiEndpoint: string;
+  protected readonly arnForExecuteApi: string;
+  protected readonly stageName?: string;
+
+  constructor(scope: Construct, id: string, private readonly props: CallApiGatewayRestApiEndpointProps) {
+    super(scope, id, props);
+
+    this.apiEndpoint = this.getApiEndpoint();
+    this.arnForExecuteApi = props.api.arnForExecuteApi(props.method, props.apiPath, props.stageName);
+    this.stageName = props.stageName;
+
+    this.taskPolicies = this.createPolicyStatements();
+  }
+
+  private getApiEndpoint(): string {
+    const apiStack = cdk.Stack.of(this.props.api);
+    return `${this.props.api.restApiId}.execute-api.${apiStack.region}.${apiStack.urlSuffix}`;
+  }
+}

packages/@aws-cdk/aws-stepfunctions-tasks/lib/apigateway/index.ts

@@ -0,0 +1,3 @@
+export * from './base-types';
+export * from './call-rest-api';
+export * from './call-http-api';

packages/@aws-cdk/aws-stepfunctions-tasks/lib/index.ts

@@ -45,3 +45,4 @@ export * from './athena/get-query-execution';
 export * from './athena/get-query-results';
 export * from './databrew/start-job-run';
 export * from './eks/call';
+export * from './apigateway';

packages/@aws-cdk/aws-stepfunctions-tasks/package.json

@@ -72,6 +72,9 @@
     "pkglint": "0.0.0"
   },
   "dependencies": {
+    "@aws-cdk/aws-apigateway": "0.0.0",
+    "@aws-cdk/aws-apigatewayv2": "0.0.0",
+    "@aws-cdk/aws-apigatewayv2-integrations": "0.0.0",
     "@aws-cdk/aws-batch": "0.0.0",
     "@aws-cdk/aws-cloudwatch": "0.0.0",
     "@aws-cdk/aws-codebuild": "0.0.0",
@@ -95,6 +98,9 @@
   },
   "homepage": "https://github.com/aws/aws-cdk",
   "peerDependencies": {
+    "@aws-cdk/aws-apigateway": "0.0.0",
+    "@aws-cdk/aws-apigatewayv2": "0.0.0",
+    "@aws-cdk/aws-apigatewayv2-integrations": "0.0.0",
     "@aws-cdk/aws-batch": "0.0.0",
     "@aws-cdk/aws-cloudwatch": "0.0.0",
     "@aws-cdk/aws-codebuild": "0.0.0",