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