logo

Third-party API integration in AWS Step-Functions

The objective of this blog is to give a basic understanding of how Step Functions incorporate third-party API integration.

Published Feb 9, 2024
Step Functions, AWS's serverless orchestration service, has long been praised for its ability to coordinate various AWS services into complex workflows, enabling developers to build scalable and reliable applications easily. By integrating with third-party APIs, it becomes even more versatile and powerful. Earlier we had to use lambda to call any external api but this advancement allows developers to simplify workflows by consolidating interactions with third-party systems. This means that developers may build more complex and robust applications and fully utilize cloud-native orchestration services. 
Here are some examples 
  1. In e-commerce, when a customer orders, it starts the state machine process, initiating payment using HTTP with the payment gateway. After payment approval, it fulfills the order, possibly using inventory and shipping APIs, and then notifies the customer through email or SMS.
  2. Step Functions trigger HTTP-based workflows for data tasks to collect data from sources like IoT devices and social media APIs. After that, it analyzes or transforms the data.
The objective of this blog is to give a basic understanding of how Step Functions incorporate third-party API integration. The only purpose of this blog is to introduce you to the HTTP task state within Step Function. I'll demonstrate this by creating a Step Function that utilizes only one HTTP task state to call a public API.
HTTP Task
An HTTP Task is a type of Task state that lets you call any public, third-party API, such as Salesforce and Stripe, in your workflows.
STEP 1:  
Go to the Step function and create a state machine. After that workflow studio will appear. Select the type of step function in the configuration and add an HTTP state.
workflow builder
STEP 2: 
I am going to use a to demonstrate the functionality. I am going to call the comments api to get comments on a particular post.
STEP 3: 
Start configuring the task details. Add the name, api endpoint, and method details. I want to get the comments based on the postId. The API endpoint should only contain the base URL without any query strings otherwise it will result in a schema validation error. I will pass postId as the input to the state and use query parameters configuration to get a result.
API Integration Configuration
STEP 4: 
Now we need to add authentication details. Authentication is a way to verify the identity of the user. Here it is handled using .
Authentication
A connection in EventBridge helps Step Functions securely communicate with external services by managing authorization details, like API keys, without exposing them directly in the workflow. You set up a connection by providing authentication information, like usernames and passwords, API keys, and OAuth. EventBridge then stores this information securely in AWS Secrets Manager. Whenever your workflow needs to interact with an external service, it uses the connection to handle authorization behind the scenes, keeping your data safe.
Let’s create a connection, Go to the EventBridge service then Api Destinations, and select the connections for creating one.
Add the details like destination type, authorization type, and parameters. For this example, I am using a username and password. 
I know you might be confused as we are calling a public Api that does not need any authorization. So the assumption with this resource is that generally, you don’t call any public that is not authorized so it is required even if the api doesn’t require it.
After this, you can go back to the stepfunction state and select the connection that you just created.
STEP 5:
I want comments based on the postId that I will pass as a query parameter. You can specify query parameters as a string, JSON array, or JSON object. Step Functions automatically URL-encodes query parameters when it calls a third-party API. You can also use a reference path to specify the query parameters at runtime.
1
2
3
"myQueryParams": {       
  "postId": "2"
}
https://jsonplaceholder.typicode.com/comments``?postId=2
All the configuration for the state is done and now we need to test the state. Recently step functions have also added test state functionality that helps you in testing the single state instead of executing the whole state machine.
Testing
In Design mode, choose Test state in the Inspector panel of Workflow Studio.
Before Testing, we need to have the role with appropriate permission to test the state. To enable an HTTP Task in your state machine to interact with a third-party API, the role responsible for executing the state machine must possess specific permissions. These include the ability to invoke HTTP endpoints (states:InvokeHTTPEndpoint), retrieve connection credentials (events:RetrieveConnectionCredentials), access secret values (secretsmanager:GetSecretValue), and describe secrets (secretsmanager:DescribeSecret).
Select the role that you just created, the inspection level, and add state input.
If everything goes well you will be able to fetch the details.
Apart from the above configurations, you can customize the information sent in the requests, modify how the requests look, and transform them to fit specific needs. Additionally, there are ways to deal with errors gracefully, ensuring that if something goes wrong, your workflow can try again or manage the situation smoothly. This adds strength and reliability to how your processes are handled.
I hope you've found something new and interesting in this blog.