# ansible.builtin.uri
Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE HTTP authentication mechanisms.

## Parameter
| Parameter          | Type                                                     | Default | Description                                                                                                                                                                                                                                                                         |
| ------------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **attributes**     | string                                                   | -       | The attributes the resulting filesystem object should have. To get supported flags look at the man page for [chattr](../../../applications/cli/chattr.md) on the target system. The = operator is assumed as default, otherwise + or - operators need to be included in the string. |
| **body**           | any                                                      | -       | The body of the http request/response to the web service. If `body_format` is set to ‘json’ it will take an already formatted JSON string or convert a data structure into JSON.                                                                                                    |
| **body_format**    | "form-urlencoded"<br>"json"<br>"raw"<br>"form-multipart" | "raw"   | The serialization format of the body. When set to `json`, `form-multipart`, or `form-urlencoded`, encodes the body argument, if needed, and automatically sets the Content-Type header accordingly.                                                                                 |
| **creates**        | path                                                     | -       | A filename, when it already exists, this step will not be run.                                                                                                                                                                                                                      |
| **dest**           | path                                                     | -       | A path of where to download the file to (if desired). If dest is a directory, the basename of the file on the remote server will be used.                                                                                                                                           |
| **headers**        | dictionary                                               | {}      | Add custom HTTP headers to a request in the format of a YAML hash                                                                                                                                                                                                                   |
| **method**         | string                                                   | "GET"   | The HTTP method of the request or response.                                                                                                                                                                                                                                         |
| **removes**        | path                                                     | -       | A filename, when it does not exist, this step will not be run.                                                                                                                                                                                                                      |
| **status_code**    | list / elements=integer                                  | \[200]  | A list of valid, numeric, HTTP status codes that signifies success of the request.                                                                                                                                                                                                  |
| **timeout**        | integer                                                  | 30      | The socket level timeout in seconds                                                                                                                                                                                                                                                 |
| **url**            | string / required                                        | -       | HTTP or HTTPS URL                                                                                                                                                                                                                                                                   |
| **url_password**   | string                                                   | -       | A password for the module to use for Digest, Basic or WSSE authentication.                                                                                                                                                                                                          |
| **url_username**   | string                                                   | -       | A username for the module to use for Digest, Basic or WSSE authentication.                                                                                                                                                                                                          |
| **validate_certs** | boolean                                                  | true    | If `false`, SSL certificates will not be validated.                                                                                                                                                                                                                                 | 

## Return Values
| Value              | Type       | When                                                | Description                                                       |
| ------------------ | ---------- | --------------------------------------------------- | ----------------------------------------------------------------- |
| **content**        | string     | status not in status_code or return_content is true | The response body content.                                        |
| **cookies**        | dictionary | success                                             | The cookie values placed in cookie jar.                           |
| **cookies_string** | string     | success                                             | The value for future request Cookie headers.                      |
| **elapsed**        | integer    | success                                             | The number of seconds that elapsed while performing the download. |
| **msg**            | string     | always                                              | The HTTP message from the request.                                |
| **path**           | string     | dest is defined                                     | destination file/path                                             |
| **redirected**     | boolean    | success                                             | Whether the request was redirected.                               |
| **status**         | integer    | always                                              | The HTTP status code from the request.                            |
| **url**            | string     | always                                              | The actual URL used for the request.                                                                  |

## Examples
```yaml
- name: Check that you can connect (GET) to a page and it returns a status 200
  ansible.builtin.uri:
    url: http://www.example.com

- name: Check that a page returns successfully but fail if the word AWESOME is not in the page contents
  ansible.builtin.uri:
    url: http://www.example.com
    return_content: true
  register: this
  failed_when: this is failed or "'AWESOME' not in this.content"

- name: Create a JIRA issue
  ansible.builtin.uri:
    url: https://your.jira.example.com/rest/api/2/issue/
    user: your_username
    password: your_pass
    method: POST
    body: "{{ lookup('ansible.builtin.file','issue.json') }}"
    force_basic_auth: true
    status_code: 201
    body_format: json

- name: Login to a form based webpage, then use the returned cookie to access the app in later tasks
  ansible.builtin.uri:
    url: https://your.form.based.auth.example.com/index.php
    method: POST
    body_format: form-urlencoded
    body:
      name: your_username
      password: your_password
      enter: Sign in
    status_code: 302
  register: login

- name: Login to a form based webpage using a list of tuples
  ansible.builtin.uri:
    url: https://your.form.based.auth.example.com/index.php
    method: POST
    body_format: form-urlencoded
    body:
    - [ name, your_username ]
    - [ password, your_password ]
    - [ enter, Sign in ]
    status_code: 302
  register: login

- name: Upload a file via multipart/form-multipart
  ansible.builtin.uri:
    url: https://httpbin.org/post
    method: POST
    body_format: form-multipart
    body:
      file1:
        filename: /bin/true
        mime_type: application/octet-stream
      file2:
        content: text based file content
        filename: fake.txt
        mime_type: text/plain
      text_form_field: value

- name: Connect to website using a previously stored cookie
  ansible.builtin.uri:
    url: https://your.form.based.auth.example.com/dashboard.php
    method: GET
    return_content: true
    headers:
      Cookie: "{{ login.cookies_string }}"

- name: Queue build of a project in Jenkins
  ansible.builtin.uri:
    url: http://{{ jenkins.host }}/job/{{ jenkins.job }}/build?token={{ jenkins.token }}
    user: "{{ jenkins.user }}"
    password: "{{ jenkins.password }}"
    method: GET
    force_basic_auth: true
    status_code: 201

- name: POST from contents of local file
  ansible.builtin.uri:
    url: https://httpbin.org/post
    method: POST
    src: file.json

- name: POST from contents of remote file
  ansible.builtin.uri:
    url: https://httpbin.org/post
    method: POST
    src: /path/to/my/file.json
    remote_src: true

- name: Create workspaces in Log analytics Azure
  ansible.builtin.uri:
    url: https://www.mms.microsoft.com/Embedded/Api/ConfigDataSources/LogManagementData/Save
    method: POST
    body_format: json
    status_code: [200, 202]
    return_content: true
    headers:
      Content-Type: application/json
      x-ms-client-workspace-path: /subscriptions/{{ sub_id }}/resourcegroups/{{ res_group }}/providers/microsoft.operationalinsights/workspaces/{{ w_spaces }}
      x-ms-client-platform: ibiza
      x-ms-client-auth-token: "{{ token_az }}"
    body:

- name: Pause play until a URL is reachable from this host
  ansible.builtin.uri:
    url: "http://192.0.2.1/some/test"
    follow_redirects: none
    method: GET
  register: _result
  until: _result.status == 200
  retries: 720 # 720 * 5 seconds = 1hour (60*60/5)
  delay: 5 # Every 5 seconds

- name: Provide SSL/TLS ciphers as a list
  uri:
    url: https://example.org
    ciphers:
      - '@SECLEVEL=2'
      - ECDH+AESGCM
      - ECDH+CHACHA20
      - ECDH+AES
      - DHE+AES
      - '!aNULL'
      - '!eNULL'
      - '!aDSS'
      - '!SHA1'
      - '!AESCCM'

- name: Provide SSL/TLS ciphers as an OpenSSL formatted cipher list
  uri:
    url: https://example.org
    ciphers: '@SECLEVEL=2:ECDH+AESGCM:ECDH+CHACHA20:ECDH+AES:DHE+AES:!aNULL:!eNULL:!aDSS:!SHA1:!AESCCM'
```