Unleashing the Power of API Orchestration with AWS Step Functions and API Gateway

11 / Jun / 2024 by Iman Abbas 0 comments

In today’s complex software landscape, applications often rely on interactions with multiple APIs to complete tasks. Managing these interactions can quickly become cumbersome, leading to code duplication, increased complexity, and potential errors. This is where API orchestration comes to the rescue.

API orchestration allows you to choreograph the calls to various APIs in a pre-defined sequence, treating them as composable building blocks for a larger functionality. This approach offers several benefits:

  • Improved code maintainability: You reduce code duplication and simplify future maintenance by centralizing the orchestration logic in a single location.
  • Increased error handling: Define centralized error handling mechanisms within the orchestration layer, improving the overall resilience of your application.
  • Enhanced scalability: Orchestration tools like AWS Step Functions enable building scalable workflows that can adapt to varying workloads.

    API Orchestartion diagram

    API Orchestration diagram


The image illustrates an architecture where an API Gateway routes client requests to various microservices, with an Orchestrator Service handling requests, aggregating responses from multiple services (Service A, B, and C), and composing the final response back to the client. The Orchestrator Service coordinates interactions among the microservices, managing the data flow and ensuring a cohesive response is returned to the client.

AWS Step Functions is a serverless orchestration service by which we can combine AWS Lambda functions and other AWS services to build complex business applications. We can author the orchestration logic in a declarative style using a JSON-based format called the Amazon States Language(ASL). AWS Step functions also provide a Work ow Studio where we can define and run our work ows.

In this article, we will introduce the concepts of AWS Step Functions and understand its working with the help of an example.

Let us first understand some basic concepts of Step Functions.

State Machine, State, and Transitions

A state machine is a mathematical model of computation consisting of different states connected with transitions. AWS Step functions also implement a state machine to represent the orchestration logic. Each step of the orchestration is represented by a state in the state machine and connected to one or more states through transitions.

They are represented by a diagram to visualize the current state of a system as shown here:


State and Transition Diagram

State and Transition Diagram

State machines contain at least one state. Transitions represent different events that allow the system to transition from one state to another state. 

Types of State

States receive input, perform actions to produce some output and pass the output to other states. States are of different types which determine the nature of the functions a state can perform. Some of the commonly used types are:

  1. Task: A state-of-type task represents a single unit of work performed by a state machine. Tasks perform all the work in a state machine. The work is performed by using an activity or an AWS Lambda function, or by passing parameters to the API actions of other services.
  2. Parallel: State of type parallel is used to trigger multiple execution branches.
  3. Map: We can dynamically iterate steps with a state-of-type map.
  4. Choice: We use this type of state as decision points within a state machine to choose among multiple execution branches.
  5. Wait: A Wait state represents a pause or delay in executing your workflow.
  6. Pass: A Pass state represents a no-op or pass-through state that passes its input to its output without performing any processing.
  7. Fail: A Fail state represents a terminal state in your workflow indicating that the execution has failed.

The state machine executes one state after another till it has no more states to execute. We will understand these concepts further by implementing a sample Generation process of an application with a state machine.

Types of State Machine: Standard vs Express

We can create two types of state machines. State machine executions differ based on the type. The type of state machine cannot be changed after the state machine is created.

  1. Standard: State machine of type: Standard should be used for long-running, durable, and auditable processes.
  2. Express: State machine of type: Express is used for high-volume, event-processing workloads such as IoT data ingestion, streaming data processing and transformation, and mobile application backends. They can run for up to five minutes.

Exploring the state machine

The state machine orchestrates the ticket generation processing and distribution:


Sample State Machine Diagram

Sample State Machine Diagram

The workflow is structured as follows:

  1. Choice State for User Selection: The workflow starts with a choice state that conditionally executes based on the user’s choice between “Fetch” or “Generate” actions.
  2. Parallel State for Data Filtering: A parallel state is used with two pass states following the choice state. Each pass state filters out specific details for calling the Ticket generation API.
  3. Lambda Function for Ticket Generation: After data filtering, a Lambda function is invoked to generate a ticket using an API call based on the filtered details.
  4. Handling Success and Failure: The workflow includes success and fail states that respond accordingly and terminate the workflow if ticket generation fails.
  5. Lambda Function for Ticket Encryption: Upon successful ticket generation, another Lambda function is triggered to perform encryption on the generated ticket.
  6. Parallel State for Distribution: Next, a parallel state is utilized to trigger: A success state indicates the completion of the workflow. and an Amazon SNS (Simple Notification Service) action that sends the encrypted ticket to a subscriber.

Connect API Gateway to Step Functions

API Gateway Integration With Step Function

API Gateway Integration With Step Function


Connecting API Gateway to AWS Step Functions allows you to trigger Step Functions workflows directly from incoming HTTP requests.

  1.  Creating a Rest API

    Navigate to the API Gateway console, and click on “Create API” in the right top corner. Click on “Build” under “REST API”.

    Creating Rest API on API Gateway

    Creating Rest API

    • Choose the API Type – select “REST API ”
    • Create a new API – select “New API”
    • Settings – provide a suitable “API name”, “Description”
    • Click “Create API” to create the base API.

2.  Configure Integration Request 

      Open the newly created API. Click on “Resources” and create a “POST” method and set the “Integration Request” following as shown in the figure.

Integration Request Page

Integration Request Page

    • Integration type – AWS Service
    • AWS Region – Set the appropriate region
    • AWS Service – Step Functions
    • Action – StartSyncExecution
    • Execution role – Role ARN to allow API Gateway to invoke Step Function API (IAM Action – “states: StartSyncExecution”)

3. Deploy the API

    Finally, deploy the API into an appropriate stage.

Deploy the API

API Deploy


Last but not least, the pricing



Step Functions charges based on the number of state transitions required to execute your application. So, every time a step in your workflow is executed, it is counted as a state transition. AWS charges you for the total number of your state transitions across all your state machines, including retries.


  • Free Tier: 4,000 state transitions per month
  • State transitions: $0.000025 PER STATE TRANSITION after that $0.025 per 1,000 state transitions


API orchestration simplifies managing modern applications by reducing code duplication and enhancing reliability. AWS Step Functions offer a powerful framework for scalable, maintainable, and resilient workflows. With robust error handling and seamless AWS integration, Step Functions streamline complex processes, enabling efficient and reliable applications that enhance the user experience.


Leave a Reply

Your email address will not be published. Required fields are marked *