Using the HTTP Request Native Action
The HTTP Request native action in Swimlane Turbine allows orchestrators to interact with APIs, whether or not a pre-existing connector for the service exists. This action facilitates sending and receiving data to/from specific API endpoints, making it a vital tool for creating comprehensive playbooks with custom outputs and enhanced performance.
Required Inputs:
- endpoint: The URL address of the API endpoint (required)
- method: The HTTP method to use (required, defaults to GET)
The action supports dynamic URL path parameters using the :variableName syntax in the endpoint URL, which are replaced with actual values at runtime. Path parameters allow you to create reusable endpoint templates. For example, an endpoint like https://api.example.com/users/:userId can have the userId path parameter replaced dynamically. To configure path parameters, use the Path Variables tab in the action configuration (see the Path Variables Tab section below).
Key Benefits
- Flexibility: Supports multiple HTTP methods (GET, POST, PUT, etc.) to handle various API interactions.
- Customizable: Allows for detailed configuration of authentication, parameters, headers, and body content to suit specific API requirements.
- Integration: Easily integrates with third-party services, enhancing workflow automation.
- Error Handling: Built-in options like retries and timeouts improve reliability and control over API interactions.
- Performance: Streamlines the automation of tasks that require external data retrieval or updates, improving operational efficiency.
Adding the HTTP Request Action
To configure an HTTP Request, drag and drop the HTTP Request action from the Add Panel, then click Configure. Follow the steps below to complete the configuration.
Request Method
Select the desired request method from the drop-down. GET is the default request method.
Authentication Tab
On the Authentication tab, you can select the appropriate authentication type for your API request. The available types are:
Parameters Tab
To add query parameters to your HTTP Request, go to the Parameters tab and click Add Parameter. Enter key-value pairs for each parameter. Query parameters are appended to the URL as ?key=value&key2=value2.
Note: Parameters can be enabled or disabled individually, allowing you to conditionally include them in requests.
Path Variables Tab
Path variables (also called path parameters) allow you to dynamically replace parts of the URL path. In your endpoint URL, use the :variableName syntax (colon followed by the variable name) to define path parameters. For example, if your endpoint is https://api.example.com/users/:userId/posts/:postId, you can define userId and postId as path variables in the Path Variables tab and set their values dynamically.
Note: The Path Variables tab may not be visible initially. It appears automatically when you use the :variableName syntax in your endpoint URL.
Example:
- Endpoint: https://api.example.com/users/:userId
- Path Variable: userId with value 123
- Resulting URL: https://api.example.com/users/123
Multiple Path Parameters:
You can use multiple path parameters in a single endpoint:
- Endpoint: https://api.example.com/api/:version/users/:userId/posts/:postId
- Path Variables:
- version with value v1
- userId with value 123
- postId with value 456
- Resulting URL: https://api.example.com/api/v1/users/123/posts/456
Path variables are useful for creating reusable endpoint templates that can be customized per request. They provide a cleaner alternative to building URLs with string concatenation.
Headers Tab
On the Headers tab, you can view auto-generated headers that will be included with your request at run-time. You can also add custom headers, such as Content-Type, to meet specific API requirements.
Body Tab
The Body tab allows you to define the data sent in the request body. Available options include None, JSON, X WWW FORM URL Encoded, Attachment, and Form Data. The default option is None.
Body Types:
- None: No body is sent with the request (default for GET, HEAD, OPTIONS, DELETE methods)
- JSON: Send JSON data with Content-Type: application/json header
- X WWW Form URL Encoded: Send form-encoded data with Content-Type: application/x-www-form-urlencoded header
- Attachment: Send a file attachment with Content-Type: application/octet-stream header
- Form Data: Send multipart form data with Content-Type: multipart/form-data header (useful for file uploads with additional fields)
Settings Tab
In the Settings tab, you can configure request settings:
- Proxy: Configure a proxy by selecting Create New Asset or choosing an existing proxy asset from the list. Proxy settings are applied via assets.
- Enable SSL certificate verification: Toggle to enable or disable SSL/TLS certificate verification (default: enabled). Warning: Disabling certificate verification reduces security and should only be used in development environments or when dealing with self-signed certificates.
- Follow Redirects: Automatically follow HTTP redirects (default: enabled)
- Allow Unsafe Legacy Renegotiation: Allow unsafe legacy TLS renegotiation (default: disabled). Only enable if required by legacy systems.
Security Note: Always enable SSL certificate verification in production environments to protect against man-in-the-middle attacks.
Outputs Tab
The Outputs tab allows you to promote action outputs for use elsewhere in the playbook. You can also mark data as sensitive if required by clicking the ellipsis icon and Mark Sensitive. Promoted outputs appear in the Promoted Playbook Outputs section.
To remove a promoted output, click the Remove button next to the promoted output.
Retry Mechanism
The Retry option allow for greater control over HTTP requests, ensuring reliability and efficiency in automation workflows.
Retry
Configure retry criteria to handle temporary failures. You can specify the number of retries and the delay between retries. Retries are useful for handling transient network issues or temporary server errors.
Example: Set up retries with exponential backoff for API calls that may occasionally fail due to network issues.
Note: Retries are configured at the playbook action level, not within the HTTP Request action itself.
Handling HTTP Responses
The HTTP Request action returns a response object that includes:
- status_code: The HTTP status code (e.g., 200, 404, 500)
- status_reason: The HTTP status reason phrase (e.g., "OK", "Not Found", "Internal Server Error")
- headers: Response headers as a record of string or string array values
- body: The response body (parsed if JSON, otherwise raw)
Accessing Response Data
You can access response data in subsequent actions using expressions:
- $actions.actionName.result.status_code - Access the status code
- $actions.actionName.result.status_reason - Access the status reason
- $actions.actionName.result.headers - Access response headers
- $actions.actionName.result.body - Access the response body
- $actions.actionName.result.body.propertyName - Access nested properties in JSON responses
Common Response Codes
- 200 OK: Request was successful.
- 201 Created: Resource was successfully created (common for POST requests).
- 400 Bad Request: Client-side error; check the request syntax, headers, or body format.
- 401 Unauthorized: Authentication error; verify credentials and authentication method.
- 403 Forbidden: Access denied; verify permissions.
- 404 Not Found: Resource not found; check the URL and path variables.
- 500 Internal Server Error: Server-side error; consider retrying or alerting.
- 502 Bad Gateway: Invalid response from upstream server.
- 503 Service Unavailable: Service temporarily unavailable; consider retrying.
Error Handling
When an HTTP request fails, the action returns an error object. There are two types of errors:
- HTTP API Error: Contains the HTTP response (status_code, headers, body) when the server responds with an error status code
- HTTP Code Error: Contains a code error (name, message) when the request fails due to network issues, timeouts, or other non-HTTP errors
Use conditional logic to check the response status code and handle errors appropriately:
Example: Check if the status code is 200 before processing the response, otherwise log the error or retry the request.
Advanced Use Cases
Example 1: Sending Data with Authentication
Scenario: Send a JSON payload to an API endpoint with Bearer Token authentication.
- Select the POST method.
- In the Authentication tab, choose Bearer Token and provide the token.
- Configure the Body tab with JSON and define the payload.
Example 2: Handling Query Parameters
Scenario: Retrieve specific data from an API by passing query parameters.
- Select the GET method.
- Add key-value pairs in the Parameters tab.
Example 3: Using Path Parameters
Scenario: Access a specific user's data using a path parameter in the endpoint URL.
- Enter an endpoint URL with a path parameter using colon syntax: https://api.example.com/users/:userId
- The Path Variables tab will appear automatically.
- In the Path Variables tab, define the userId variable and set its value (e.g., 123).
- The resulting URL will be: https://api.example.com/users/123
Example 4: Handling Paginated Responses
Scenario: Many APIs paginate large datasets. Here's how you can handle this scenario:
- Send the initial request and store the response.
- Check for a pagination token or next URL in the response.
- Repeat the request using the next URL or token until all pages are retrieved.
Security Considerations
When interacting with APIs, it's crucial to follow best practices to ensure security:
- Validate SSL Certificates: Always enable SSL certificate verification to protect against man-in-the-middle attacks.
- Secure Credentials: Use environment variables or secure vaults to manage sensitive information like API keys or tokens.
- Limit Data Exposure: Only promote outputs that are necessary, and mark sensitive data appropriately to prevent unintentional exposure.
Troubleshooting
- Request Fails with "endpoint is required": Ensure you have provided an endpoint URL in the action configuration. The endpoint field is required.
- Request Fails with "method is required": Ensure you have selected an HTTP method. The method defaults to GET but must be explicitly set.
- Request Fails with 401 Unauthorized: Ensure the correct authentication method and credentials are provided. Verify that tokens or API keys haven't expired.
- Request Fails with 400 Bad Request: Check that:
- The request body format matches the API's expectations (JSON vs form-encoded)
- Required headers are included (especially Content-Type)
- Query parameters and path variables are correctly formatted
- Path Variables Not Replaced: Ensure path variables are defined in the Path Variables tab and that the endpoint URL uses the :variableName syntax (colon followed by the variable name). Variable names are case-sensitive and must match exactly between the endpoint URL and the Path Variables tab. If the Path Variables tab is not visible, add a path parameter using the :variableName syntax in your endpoint URL (e.g., https://api.example.com/users/:userId).
- Unexpected Response Format: Verify the API documentation and ensure your headers and body match the expected format. Check the response Content-Type header to understand the response format.
- Timeout Issues: Increase the timeout settings at the action level or check network stability. Consider using retry logic for transient network issues.
- SSL Certificate Errors: If you encounter SSL certificate errors, verify that:
- SSL certificate verification is enabled (recommended)
- The server's certificate is valid and trusted
- Only disable certificate verification in development environments
- Attachment Not Sent: When using the Attachment body type, ensure:
- The file reference is correct
- For arrays of files, use an expression to select a specific file (e.g., $inputs.files[0])
- Attachments are not used during test runs (not supported)
Best Practices
- Use Secure Authentication: Always prefer secure methods like OAuth 2.0 or Bearer Tokens over Basic Auth. Store sensitive credentials in environment variables or secure assets rather than hardcoding them.
- Validate Required Fields: Always ensure the endpoint and method are configured. Use path variables for dynamic endpoints rather than string concatenation.
- Handle Errors Gracefully: Use conditional logic to check response status codes and handle errors appropriately. Consider implementing retry logic for transient failures.
- Test API Endpoints: Validate API endpoints and configurations in a testing environment before deploying them in production. Test with various response scenarios including success and error cases.
- Use Descriptive Variable Names: Clearly label your parameters, headers, and path variables for easy identification and debugging.
- Enable SSL Verification: Always enable SSL certificate verification in production environments. Only disable it in development when necessary.
- Structure Request Bodies Properly: Match the Content-Type header with the body format (JSON, form-encoded, etc.) as expected by the API.
- Use Path Variables for Dynamic URLs: Instead of building URLs with string concatenation, use path variables with the :variableName syntax (colon followed by the variable name) for cleaner, more maintainable code. Define the path variables in the Path Variables tab to set their values dynamically.
- Monitor Response Sizes: Be aware of response size limits. Large responses may need to be handled differently or paginated.
- Document API Contracts: Document the expected request format, headers, and response structure for your team to ensure consistency.
Use Cases
For examples of how to use the HTTP Request action, see the HTTP Request use case.