# Calling APIs from Rundeck

Modern applications use the HTTP (opens new window) protocol to communicate with each other and send or obtain information from any web service using HTTP methods (opens new window) like GET, POST, or PUT. For example, to obtain a valid user ID from a web service to use it later in another process/application.

To make those HTTP calls we can use an inline-script (opens new window)] with a cURL (opens new window) command inside, curl is used in scripts or commands to transfer data and it’s available for any operating system. But this implies maintaining a lot of code inside a Rundeck workflow.

Rundeck’s Job Steps offer a more user-friendly way to make these calls. For HTTP calls, use the HTTP Workflow Step Plugin (opens new window) in Rundeck. This plugin will send HTTP calls to any web service or HTTP endpoint. The returned data can then be used in subsequent steps. (Check out our Passing Variables guide).

If you are using our Enterprise version the plugin is already bundled with your installation. Skip straight to the exercises.

# Community Version Prerequisite

The HTTP Workflows Step plugin isn’t bundled with the Rundeck Community version (is out-of-the-box with Process Automation (opens new window)), these steps show you how to install it.

  1. Go to the System Menu (Gear Icon in upper right) > Plugins > Upload Plugin.
  2. Copy the plugin file location from the repository (Latest link as of last update is below)
    Upload Plugin
    Upload Plugin
  3. Paste it on the Plugin URL textbox, and click on the Install button. Plugin Installed!

An alternative method to install the plugin is to download the .jar file directly from the repository (opens new window) and put it on the libext directory (at /var/lib/rundeck/libext` on RPM / DEB based installations or$RDECK_BASE/libext` directory on WAR based installations). Just copy the the .jar to the folder, no restart is needed.

# Exercise


For this exercise we will use the site httpbin.org (opens new window) test website, httpbin.org (opens new window) is a simple HTTP request and response service written in python by Ken Reitz. This is not a site owned or run by PagerDuty. Note: Don't send any sensitive data. This site is simply used as a test. If you would like to run your own their site has more information about using their Docker Images (opens new window).

  1. Go to the jobs page.
  2. Click on the Create a new job button.
  3. On the Details tab, give your job a name.
  4. On the Workflow tab click on the Add a step button.
  5. Choose the step named HTTP Request Node Step from the Workflow steps tab (Do not use the Node Steps one for this exercise). HTTP Request Workflow Step
  6. Put https://httpbin.org/anything URL into “Remote URL”.
  7. Select POST in the HTTP Method list. Other methods available are: GET, PUT, PATCH, DELETE, HEAD, OPTIONS.
  8. Put {"MyHeader":"test"} in the headers section (headers must be defined as JSON or YAML format). Don't send any potentially sensitive data.
  9. In the Body section put {"myBodyValues":[{"body1":"value1"},{"body2":"value2"}]}. Don't send any potentially sensitive data.
  10. Enable the Print Response? checkbox, to see the web service / endpoint response on the job output.
  11. Leave all the other settings as the defaults.
  12. Click Save on the HTTP Request Job Step. HTTP Request Saved
  13. Scroll down and click on the Create button.
  14. Then click on the Run Job Now button.

# Other Parameters

Other parameters available:

  • Request Timeout (How long to wait for a request to complete before failing).
  • Validate SSL Certificates (opens new window) (true or false, validate that SSL certificates are trusted, match the hostname, etc.)
  • Authentication section. If the HTTP service uses Basic / OAuth2 (opens new window) authentication. On Basic Auth it’s possible to define the user and password from the Rundeck Key Storage. On OAuth 2.0 add the OAuth Token URL and OAuth Validate URL.
  • Validate Response can check the HTTP response code (opens new window) that is returned and fail the step if it is not the expected value. (typically looking for 200)
  • Proxy Settings section, if the HTTP service is behind a proxy server, you can define the Proxy IP address and port.

# Additional Information