Submit a GET request to a REST API endpoint - Interact with web services - Ansible module uri
How to retrieve a JSON list of users via a GET request to a REST API web service HTTPS endpoint from a remote Linux host in a few lines of Ansible code.
How to submit a GET request to a REST API endpoint with Ansible?
I’m going to show you a live demo and some simple Ansible code. I’m Luca Berton and welcome to today’s episode of Ansible Pilot.
Ansible submits a GET request to a REST API endpoint
- ansible.builtin.uri
- Interacts with web services supports Digest, Basic, and WSSE HTTP authentication mechanisms
Today we’re talking about Ansible module uri.
The full name is ansible.builtin.uri, which means that is part of the collection of modules “builtin” with ansible and shipped with it.
It’s a module pretty stable and out for years and it works in a different variety of POSIX operating systems.
It interacts with web services and supports Digest, Basic, and WSSE HTTP authentication mechanisms.
If you need to download content, use the Ansible ansible.builtin.get_url module.
For Windows targets, use the ansible.windows.win_uri module instead.
Parameters
- url string - (http|https)://host.domain[:port]/path
- method string - “GET”, “POST”, “PUT”, “PATCH”, “DELETE”
- user (url_username), password (url_password) string - username, password credentials
- force_basic_auth boolean - no,yes - Basic authentication header
- status_code list/integer - [200, 202]
- headers dictionary - custom HTTP headers, Content-Type
- body_format string - raw, json,
form-urlencoded,form-multipart - body raw - request body
- return_content boolean - no/yes - return the body of the response
- timeout integer - 30 seconds
This module has some parameters to perform any tasks.
The only required is “url”, where you specify the API URL.
The parameter “method” specifies the HTTP method of the request: “GET”, “POST”, “PUT”, “PATCH”, “DELETE”.
The parameters “user” and “password” specify the credentials to access the API. Several authentications methods are supported, for the simplest is the Basic HTTP authentication remember to enable the “force_basic_auth” boolean.
The parameter “status_code” sets the expected single or list of expected HTTP status codes. The most commons are okay is 200, not fount is 404, and so on… If Please note that Ansible is going to return an error if the status code is different.
The parameter “headers” set the custom HTTP headers and HTTP Content-Type.
The parameter “body_format” sets the serialization format of the body content. Default is raw, but you could customize it to send an image for example. There are some restrictions with Content-Type and some serializations.
The parameter “return_content” is very important to return the body of the response as a “content” key in the dictionary result.
The default timeout is set to 30 seconds, but you could customize it with the “timeout” parameter.
Links
- https://reqres.in/
- https://reqres.in/api/users?page=2
- https://docs.ansible.com/ansible/latest/collections/ansible/builtin/uri_module.html
The Best Resources For Ansible
Video Course
Printed Book
eBooks
- Ansible by Examples: 200+ Automation Examples For Linux and Windows System Administrator and DevOps
- Ansible For Windows By Examples: 50+ Automation Examples For Windows System Administrator And DevOps
- Ansible For Linux by Examples: 100+ Automation Examples For Linux System Administrator and DevOps
- Ansible Linux Filesystem By Examples: 40+ Automation Examples on Linux File and Directory Operation for Modern IT Infrastructure
- Ansible For Containers and Kubernetes By Examples: 20+ Automation Examples To Automate Containers, Kubernetes and OpenShift
- Ansible For Security by Examples: 100+ Automation Examples to Automate Security and Verify Compliance for IT Modern Infrastructure
- Ansible Tips and Tricks: 10+ Ansible Examples to Save Time and Automate More Tasks
- Ansible Linux Users & Groups By Examples: 20+ Automation Examples on Linux Users and Groups Operation for Modern IT Infrastructure
- Ansible For PostgreSQL by Examples: 10+ Examples To Automate Your PostgreSQL database
- Ansible For Amazon Web Services AWS By Examples: 10+ Examples To Automate Your AWS Modern Infrastructure
demo
Let’s jump into a real-life playbook on how to submit a GET request to a REST API endpoint with Ansible.
code
- get_list_users.yml
---
- name: uri module demo
hosts: all
become: false
vars:
server: "https://reqres.in"
endpoint: "/api/users?page=2"
tasks:
- name: list users
ansible.builtin.uri:
url: "{{ server }}{{ endpoint }}"
method: GET
status_code: 200
timeout: 30
register: result
- name: debug
ansible.builtin.debug:
var: result.json.data
API
browser result (https://reqres.in/api/users?page=2):
{"page":2,"per_page":6,"total":12,"total_pages":2,"data":[{"id":7,"email":"[email protected]","first_name":"Michael","last_name":"Lawson","avatar":"https://reqres.in/img/faces/7-image.jpg"},{"id":8,"email":"[email protected]","first_name":"Lindsay","last_name":"Ferguson","avatar":"https://reqres.in/img/faces/8-image.jpg"},{"id":9,"email":"[email protected]","first_name":"Tobias","last_name":"Funke","avatar":"https://reqres.in/img/faces/9-image.jpg"},{"id":10,"email":"[email protected]","first_name":"Byron","last_name":"Fields","avatar":"https://reqres.in/img/faces/10-image.jpg"},{"id":11,"email":"[email protected]","first_name":"George","last_name":"Edwards","avatar":"https://reqres.in/img/faces/11-image.jpg"},{"id":12,"email":"[email protected]","first_name":"Rachel","last_name":"Howell","avatar":"https://reqres.in/img/faces/12-image.jpg"}],"support":{"url":"https://reqres.in/#support-heading","text":"To keep ReqRes free, contributions towards server costs are appreciated!"}}
execution
$ ansible-playbook -i virtualmachines/demo/inventory interract\ webservices/list_users.yml
PLAY [uri module demo] ****************************************************************************
TASK [Gathering Facts] ****************************************************************************
ok: [demo.example.com]
TASK [list users] *********************************************************************************
ok: [demo.example.com]
TASK [debug] **************************************************************************************
ok: [demo.example.com] => {
"result.json.data": [
{
"avatar": "https://reqres.in/img/faces/7-image.jpg",
"email": "[email protected]",
"first_name": "Michael",
"id": 7,
"last_name": "Lawson"
},
{
"avatar": "https://reqres.in/img/faces/8-image.jpg",
"email": "[email protected]",
"first_name": "Lindsay",
"id": 8,
"last_name": "Ferguson"
},
{
"avatar": "https://reqres.in/img/faces/9-image.jpg",
"email": "[email protected]",
"first_name": "Tobias",
"id": 9,
"last_name": "Funke"
},
{
"avatar": "https://reqres.in/img/faces/10-image.jpg",
"email": "[email protected]",
"first_name": "Byron",
"id": 10,
"last_name": "Fields"
},
{
"avatar": "https://reqres.in/img/faces/11-image.jpg",
"email": "[email protected]",
"first_name": "George",
"id": 11,
"last_name": "Edwards"
},
{
"avatar": "https://reqres.in/img/faces/12-image.jpg",
"email": "[email protected]",
"first_name": "Rachel",
"id": 12,
"last_name": "Howell"
}
]
}
Recap
Now you know how to submit a GET request to a REST API endpoint with Ansible. Subscribe to the YouTube channel, Medium, Website, Twitter, and Substack to not miss the next episode of the Ansible Pilot.
Academy
Learn the Ansible automation technology with some real-life examples in my
My book Ansible By Examples: 200+ Automation Examples For Linux and Windows System Administrator and DevOps
Donate
Want to keep this project going? Please donate
