Creating a REST Interface for our State Machine with API Gateway
Start course

In this course, we will create a multi-tier serverless architecture on AWS using Amazon API Gateway, AWS Lambda, AWS Step Functions, and Amazon Polly text to speech. This is a hands-on course where you will learn how to create serverless functions, data access, business logic, and integration layers on AWS. Also, you will learn how to create a presentation layer for your application using the client SDK generated by Amazon API Gateway. We will then host the application on Amazon S3.

Learning Objectives

By the end of this course, you will be able to recognize and implement an end to end workflow built in the Amazon Cloud using Serverless components.

Intended Audience

This course is intended for developers or DevOps engineers who want to create serverless applications on AWS, or who may be considering migrating their existing web applications to AWS.


A basic familiarity with Amazon API Gateway, Lambda, DynamoDb, S3, and AWS Step functions is required for this course. Some knowledge of building web applications using HTML and JavaScript will also be helpful.


The GitHub repository for this course is available here:


Hello and welcome back. In this lecture we'll create a REST API for the state machine created in the previous video through Amazon API Gateway. API Gateway offers direct integration with step functions allowing us to perform various actions on step functions with REST APIs. These include actions at the execution level like start execution, stop execution, describe execution and many other actions down to the activity level as well. We'll use two actions, start execution and describe execution for our demo here to create an API which can start the state machine execution through a POST call and also get the execution details through a get call. So, let's go to the API Gateway console and create a new API. Let's call it step functions API. Under the root resource, create a POST method. For integration type select AWS Service and then the region where your step function's located. In our case it's us-east-2. For AWS Service choose Step Functions. For HTTP method choose POST. For action type use action name. It's already selected by default. So, I'll just write the action name StartExecution here and I'll give here the ARN of a role that I have already created of type API Gateway and we'll give full access to step function's policy also attached to it and then just click on save. We'll quickly test our POST method. It requires a chase on input as a request body like this which includes input to the state machine, name of the execution and state machine ARN which needs to be started. So, if we hit test now it should return execution ARN and start date like this. Our POST method is working as expected and the state machine execution is started. Now let's create a get method which will retrieve the details of our execution including input, output and start and end dates etc. Under the root resource create a get method. Just like the POST method, choose integration type to be AWS Service and correct region here. AWS Service is step functions and HTTP method is POST. Note that although the underlying call is POST, we're still using get method to encapsulate the call because this action will read the current state of execution of the state machine and in REST APIs reads are typically modeled using gets. For action name type describe execution and to roll ARN, and save. Now, in the get method request describe execution action requires the execution ARN of the state machine as the input which we want to pass as a query string in our URL. So, we'll need to add a URL query string parameter in the method request. Let's call it ExecutionARN. Then in the integration request, we'll map the query string parameter ExecutionARN in the body mapping templates to transform the input to the required parameter ExecutionARN in JSON format as required by STEP function's API. And that's all we need in our call to get a response back from STEP functions about the state of execution of the state machine. Okay, let's quickly test our get method by providing the execution ARN of the last execution of the state machine. Let me copy the execution ARN from the step function's console and here we go, we got our response back with all the parameters like ExecutionARN, state machine ARN, input, output etc. We'll use the output return from this call in our application front end. We'll also need to enable calls here to allow access to requests from domains other than the API domain itself. I'll select the root resource, and click on actions and then choose enable calls and by default it will allow access to anyone on the internet to our API. For more secure implementation, you can specify specific domains here instead of a wildcard. One last thing before our API is ready for prime time is to deploy the API on a stage so that we can generate the client SDK required for front end development. Check out the next video to learn how to create the front end for this API to complete our serverless application.

About the Author

Tehreem is a Sr. Software Engineer with passion in Cloud Technologies, Big Data analytics, Software Testing and Automation. She has over 10 years of work experience comprising of her tenure at ServiceNow, Microsoft and Harmonic Inc. Most recently she has been developing learning content in-line with the emergence of Public Clouds and XaaS platforms with focus on AWS, Microsoft Azure and GCP. Tehreem resides in BayArea, CA with her family and when not working she enjoys nature/outdoors, movies and fine dining.