Ansible uri Module: Make HTTP Requests and API Calls (Complete Guide)

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_result

See 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: 5

Download 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.gz

See 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

• Ansible get_url: Download Files from URLs • Ansible Lookup Plugins: Fetch External Data