Ansible uri Module: Make HTTP Requests and API Calls (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: security-compliance
How to use Ansible uri module for HTTP GET, POST, PUT, DELETE requests. Call REST APIs, check health endpoints, download JSON. Complete guide with examples.
Ansible uri Module: Make HTTP Requests and API Calls (Complete Guide)
The ansible.builtin.uri module interact with HTTP/HTTPS web services. This guide covers all common use cases with practical playbook examples.
See also: Ansible uri Module: REST API Requests (GET, POST, PUT, DELETE)
GET Request
- name: Check website is up
ansible.builtin.uri:
url: https://example.com
method: GET
status_code: 200
register: response
- name: Get JSON from API
ansible.builtin.uri:
url: https://api.example.com/v1/status
method: GET
return_content: true
headers:
Authorization: "Bearer {{ vault_api_token }}"
register: api_response
- name: Use API data
ansible.builtin.debug:
msg: "Version: {{ (api_response.content | from_json).version }}"POST Request
- name: Create resource via API
ansible.builtin.uri:
url: https://api.example.com/v1/users
method: POST
body_format: json
body:
name: "{{ user_name }}"
email: "{{ user_email }}"
role: admin
headers:
Authorization: "Bearer {{ vault_api_token }}"
Content-Type: application/json
status_code: [200, 201]
register: create_resultSee also: Ansible URI Module: REST API Authentication & HTTP Requests Guide
Health Check with Retries
- name: Wait for application health check
ansible.builtin.uri:
url: "http://{{ inventory_hostname }}:8080/health"
method: GET
status_code: 200
register: health
until: health.status == 200
retries: 30
delay: 5Download a File
- name: Download release artifact
ansible.builtin.uri:
url: "https://releases.example.com/app-{{ version }}.tar.gz"
dest: /tmp/app-release.tar.gz
creates: /tmp/app-release.tar.gzSee also: Publishing Ansible Collections to Ansible Galaxy and Automation Hub
PUT and DELETE
- name: Update resource
ansible.builtin.uri:
url: "https://api.example.com/v1/config/{{ config_id }}"
method: PUT
body_format: json
body:
setting: new_value
headers:
Authorization: "Bearer {{ vault_api_token }}"
- name: Delete resource
ansible.builtin.uri:
url: "https://api.example.com/v1/users/{{ user_id }}"
method: DELETE
headers:
Authorization: "Bearer {{ vault_api_token }}"
status_code: [200, 204]Handle Authentication
# Basic auth
- name: API with basic auth
ansible.builtin.uri:
url: https://api.example.com/data
url_username: "{{ vault_api_user }}"
url_password: "{{ vault_api_pass }}"
force_basic_auth: true
# OAuth token
- name: Get OAuth token
ansible.builtin.uri:
url: https://auth.example.com/oauth/token
method: POST
body_format: form-urlencoded
body:
grant_type: client_credentials
client_id: "{{ vault_client_id }}"
client_secret: "{{ vault_client_secret }}"
return_content: true
register: token_response
- name: Use token
ansible.builtin.uri:
url: https://api.example.com/data
headers:
Authorization: "Bearer {{ (token_response.content | from_json).access_token }}"FAQ
How do I make HTTP requests in Ansible?
Use ansible.builtin.uri with url, method, and optional body. It supports GET, POST, PUT, DELETE, PATCH, and all HTTP methods. Use return_content: true to capture response body.
How do I call a REST API from Ansible?
Use ansible.builtin.uri with body_format: json and authentication headers. Register the response to use API data in subsequent tasks. Use retries for resilient API calls.
What is the difference between uri and get_url modules?
uri is for API interactions (any HTTP method, response parsing). get_url is specifically for downloading files to disk. Use uri for APIs, get_url for file downloads.
Conclusion
The ansible.builtin.uri module is a versatile tool for interact with HTTP/HTTPS web services. Use the examples above as starting points and adapt them to your infrastructure needs.
Related Articles
Category: security-compliance