Getting Started with the API
Getting Started with the API
Using or testing API calls as a part of any integration or development process could be cumbersome due to the big amount of API endpoints that any modern web application contains. Also, since it's very easy to pile up large numbers of calls in scripts scattered in different places, a good solution is to manage that in one place.
In this document, we learn how to centralize Rundeck API calls using the Postman application, and provide a way to export those calls to any script or programming language.
The Rundeck API
Rundeck provides a Web API for use with your applications. An API (Application Programming Interface) is a set of functions (called Endpoints) that allows applications to access data and interact with a Web Application, e.g: a test curl POST call to run a job from the shell:
curl --location --request POST 'http://localhost:4440/api/41/job/50aa1e22-3e75-41fd-aa07-0cc5e5b2666e/run' \
--header 'Accept: application/json' \
--header 'X-Rundeck-Auth-Token: EsMOdQNJy43Jg3WbtkGEGp3L3T1yhZ4w' \
--header 'Content-Type: application/json' \
--data-raw ''
An API delivers a user response to a Rundeck Instance and sends the proper response back to a user.
You can find a complete Rundeck API reference here.
Postman
Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs. With Postman it's possible to create a Collection and then save any API endpoint call there. Postman is available here, and the installation process is described here.
Running the Welcome Project and New User Token Creation
This tutorial is based on the Welcome Project and Community Welcome Project (here is how to run both projects). You can use both to test some Rundeck API endpoints.
Launch the Welcome Project (or Community Welcome Project) following these instructions.
Enter as an admin user (user:
admin
, password:admin
).Click on the user icon (upper right) and then click on “Profile”.
- Click on the "+" button.
- Give a name to the token and then save it.
Creating a Postman Collection and The First Rundeck API Call (Rundeck System Info)
- Launch Postman and then click on the "Create a new Collection" link.
- Give it a name, in the “variables” tab define the Rundeck instance hostname (as
localhost
in this example), port (4440
as default Rundeck TCP port), and API version (41
at this moment), this variable definition avoids the need to edit each request in case of hostname/port/api version change. Then click on the "Save" button.
- Now go click on the “Authorization” tab, select “API Key” on Type, put
X-Rundeck-Auth-Token
in the “Key” textbox, and add the variablerdeck_api_token
created in the previous step (using the{{rdeck_api_token}}
notation), finally on “Add to” list, select “Header” and click on the Save button.
The Collection is created so now we can get some data from Rundeck using the API.
- Click on the "Add a request" link from the Scratch Pad panel.
- To get the Rundeck System Information select the "GET" method and the following endpoint:
{{rdeck_hostname}}:{{rdeck_port}}/api/{{rdeck_api_version}}/system/info
Then click on the "Headers" tab and add a new one with Accept
as a key and application/json
as a value.
To test it, just click on the "Send" blue button at the right of the endpoint string.
Running a Rundeck Job
To run a Rundeck Job from the API, the method "POST" is needed.
- On Postman click on the “...” next to the Rundeck collection (left panel), then select “Add Request”, after that, an empty request is created.
- Select the "POST" method and the following endpoint:
{rdeck_hostname}}:{{rdeck_port}}/api/{{rdeck_api_version}}/job/3a13fca8-4d42-417e-812b-5f2f700dccb3/run
The 3a13fca8-4d42-417e-812b-5f2f700dccb3
string is the Rundeck job ID.
In the "Headers" tab add a new request with
Accept
as a key andapplication/json
as a value.Click on Save Icon.
Give it a name, select the Rundeck Collection and then click on the "Save" button.
Now, call the endpoint by clicking on the "Send" button.
Running a Job with Options
The Welcome Project job called "Using Input Options in command and scripts" contains an option to test it on Postman.
On Postman click on the "+" tab to create a new request.
Select the "POST" method and the following endpoint:
{rdeck_hostname}}:{{rdeck_port}}/api/{{rdeck_api_version}}/job/3a13fca8-4d42-417e-812b-5f2f700dccb3/run
The 05029d94-bde4-487a-ac0d-03fc7f659c38
string is the job ID.
In the "Headers" tab add a new one with
Accept
as a key andapplication/json
as a value.Now click on the Body tab, select "raw" in the left dropdown menu and then select "JSON". Now put the following content:
{
"options": {
"input_key":"HelloWorld"
}
}
Click on Save Icon.
Give it a name, select the Rundeck Collection and then click on the "Save" button.
Now, call the endpoint by clicking on the "Send" button.
Go to the Rundeck instance, click on the Activity icon (left) and see the last execution.
Export Postman Requests to Any Language
Postman provides the ability to export a request to other languages like Python or JavaScript.
To export a request, click on the code icon (right) and select the language. The API call should be displayed and you can export it.
Resources
A complete Rundeck API reference is available here.
Here are a lot of examples of Postman and Rundeck API endpoints calls.