If you are not familiar with modules, check out Ansible - Getting Started with Modules.
ansible.builtin.uri can be used to submit a POST request to an API. For example, here is how you could submit a POST request to http://example.com/api/v1.
---
- hosts: all
tasks:
- name: submit a POST request to http://example.com/api/v1
ansible.builtin.uri:
url: http://example.com/api/v1
method: POST
...
Sometimes the API will return a response code that Ansible thinks indicates that the POST request failed, when in fact the POST request was successful. For example, I had an REST API that was returning a status code of 204 when the reqeust was successful, and Ansible interpreted this as a failure. To account for this, I added failed_when so that the task was not failed when the response code was 204.
---
- hosts: all
tasks:
- name: submit a POST request to http://example.com/api/v1
ansible.builtin.uri:
url: http://example.com/api/v1
method: POST
register: out
failed_when: out.status != 204
...
If the API requires basic authentication, these options can be included.
- force_basic_auth
- url_username
- url_password
---
- hosts: all
tasks:
- name: submit POST request to http://example.com/api/v1
ansible.builtin.uri:
url: http://example.com/api/v1
method: POST
force_basic_auth: yes
url_username: john.doe
url_password: itsasecret
...
If you want to POST payload data to the API, body and body_format can be used. For example, to POST JSON.
---
- hosts: all
tasks:
- name: submit POST request to http://example.com/api/v1
ansible.builtin.uri:
url: http://example.com/api/v1
method: POST
body_format: json
body: "{ \"foo\": \"bar\" }"
...
If the URL includes parameters (key/value pairs), you may want or need to include body_format: form-urlencoded.
---
- hosts: all
tasks:
- name: submit POST request to http://example.com/api/v1?foo=hello&bar=world
ansible.builtin.uri:
url: http://example.com/api/v1?foo=hello&bar=world
method: POST
body_format: form-urlencoded
...
And here is an example with an oAuth bearer token passed in as a header.
---
- hosts: all
tasks:
- name: submit POST request to http://example.com/api/v1
ansible.builtin.uri:
url: http://example.com/api/v1
method: POST
headers:
Authorization: "Bearer abc123"
Accept: application/json
Content-Type: application/json
...
If the POST request is successful, something like this should be returned.
ok: [server1.example.com] => {
"out": {
"msg": "[200]: OK",
"pragma": "no-cache",
"redirected": false,
"server": "******",
"set_cookie": "JSESSIONID=7B01203DD8CA499717F5BD3B36A6D929; Path=/example; HttpOnly; SameSite=Strict",
"status": 200,
"url": "http://example.com/api/v1?foo=hello&bar=world",
"x_content_type_options": "NOSNIFF",
"x_frame_options": "SAMEORIGIN",
"x_xss_protection": "1; mode=block"
}
If you will be passing in unique URL string, it's probably a good idea to use set_fact and urlencode.
---
- hosts: all
tasks:
- ansible.builtin.set_fact:
my_url: input_string | urlencode
- name: submit POST request
ansible.builtin.uri:
url: "{{ my_url }}"
method: POST
body_format: form-urlencoded
...
Did you find this article helpful?
If so, consider buying me a coffee over at