Ansible AWX API Examples for Network Engineers
What is an API request?
An API request is how one program or system (in this case, Ansible AWX) communicates with another program or system (like a script or a web application). API stands for Application Programming Interface, which allows different software to talk to each other and exchange data or perform actions. When you send an API request, you are essentially asking the system to do something for you, like retrieving data, updating records, or starting a job.
In the context of Ansible AWX, you can use the API to interact programmatically with your Ansible automation environment. Instead of manually clicking through the AWX interface, you can use the API to automate tasks like creating jobs, listing inventories, or checking job statuses.
Ansible AWX API Tutorial – Ansible REST API
Getting Started with Ansible AWX API Requests
Before diving into specific API requests, you’ll need to understand the following:
HTTP Methods: You’ll usually use GET (retrieve data), POST (create data), PUT (update data), or DELETE (remove data) methods.
API Endpoint: This is the URL of the AWX server where the API can be accessed.
Authentication: AWX API typically uses either token-based or basic authentication.
AWX API Documentation
The full list of API commands available can be found in the official documentation on the
Ansible API Reference Guide page
It still refers to Ansible Tower but all the information is the same. Ansible Tower was commercial product that is based on the open-source AWX project, it is now called Ansible Automation Platform.
Ansible AWX API Authentication
AWX API Token
If you are going to interact with the Ansible AWX API it is much easier if you get an API token to use as your authentication method. To get an API token follow these simple steps.
1. Log into your AWX Dashboard and click on your username, then click on User Details
2. Click on Tokens
3. Click on Create Token & select Read or Write
The only required element here is Scope – This defines if the token will provide read or write access. You can also enter a description for your reference. Click Create Token
Your Token will be shown one time only! So make a note of it.
You can now use this token for all the tasks below.
There are many ways to interact with the API in AWX, you can use a curl request, you could write a Python script or you could use a tool like Postman, we will cover all options here.
The first few options will start by using curl as an easy way to get started.
It is assumed that you already have an Ansible AWX available
Ansible AWX API Examples GitHub
All the code below can be found on this GitHub Repo
If you are new to Ansible AWX – check out my guide on the basics including how to install AWX and basic AWX terminology – Ansible AWX Guide for Beginners
AWX API Examples
10 Simple API Requests for Ansible AWX Beginners
1. Get a List of All Jobs from AWX
Get Request
curl -X GET https://<AWX_SERVER>/api/v2/jobs/<JOB_ID>/ -H "Authorization: Bearer <YOUR_API_TOKEN>"
This will output a lot of text in an unformatted format if you outputting to a terminal so it’s better to output it in Json format, you can do this by adding | python -m json.tool to the end of your curl request.
This is what my full curl request looks like for my lab server
curl -X GET http://192.168.1.159:30080/api/v2/jobs/ -H "Authorization: Bearer jgwOpzWikluZCR7CtcLT0G5hFKBwLb" | python -m json.tool
This is a snippet of the output you should see
2. Get Details of a Specific Job
Once you have all the output above you can pick the ID of a specific job and details of just that, you can also find this in the GUI
3. List all Inventories using API
4. Create a New Inventory using API
5. Get a List of Job Templates
6. AWX API Launch Job
7. Get a List of Hosts in an Inventory
8. Add a Host to an Inventory
9. Get Job Status
10. Delete a Job
These simple examples will help you start interacting with Ansible AWX’s API. By making API requests, you can automate a variety of tasks within AWX, saving time and reducing manual steps. Whether you’re automating the creation of job templates, launching jobs, or managing inventories, AWX’s API provides a powerful way to streamline your automation workflows.
For more advanced usage, you can explore other parts of the AWX API, such as managing users, organisations, and projects.
What is Ansible Tower?
Ansible Tower is a web-based platform that helps manage IT automation tasks. It was the previous paid / supported version of Ansible AWX which is now called Automation Controller, it is also now wrapped up in a suite of tools called Ansible Automation Platform. Ansibe AWX is the upstream open source version of Ansible Controller.
More information here:
https://www.redhat.com/en/technologies/management/ansible/compare-awx-vs-ansible-automation-platform
Leave a Reply