aci_rest: Fix error handling and improve documentation (#36295)

This PR includes:
- A fix for a recently introduced issue wrt. error handling
- Added integration tests for provoked errors
- Influence standard return values using aci library for aci_rest
- Add proxy support documentation
- Documentation update related to #34175

7 files changed, 209 insertions, 27 deletions

diff --git a/test/integration/targets/aci_rest/tasks/error_handling.yml b/test/integration/targets/aci_rest/tasks/error_handling.yml
new file mode 100644
index 0000000000..499a69efad
--- /dev/null
+++ b/test/integration/targets/aci_rest/tasks/error_handling.yml
@@ -0,0 +1,195 @@
+# Test code for the ACI modules
+# Copyright: (c) 2018, Dag Wieers (@dagwieers) <dag@wieers.com>
+
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+
+# PROVOKE ERRORS
+- name: Error on name resolution
+  aci_rest:
+    host: foo.bar.cisco.com
+    username: '{{ aci_username }}'
+    password: '{{ aci_password }}'
+    validate_certs: '{{ aci_validate_certs | default(false) }}'
+    use_ssl: '{{ aci_use_ssl | default(true) }}'
+    use_proxy: '{{ aci_use_proxy | default(true) }}'
+    output_level: debug
+    path: /api/mo/uni.json
+    method: post
+    content:
+      fvTenant:
+        attributes:
+          name: ansible_test
+  ignore_errors: yes
+  register: error_on_name_resolution
+
+- name: Verify error_on_name_resolution
+  assert:
+    that:
+    - error_on_name_resolution.failed == true
+    - "error_on_name_resolution.msg == 'Connection failed for https://foo.bar.cisco.com/api/aaaLogin.json. Request failed: <urlopen error [Errno -2] Name or service not known>'"
+    - "'current' not in error_on_name_resolution"
+    - "'previous' not in error_on_name_resolution"
+    - "'sent' not in error_on_name_resolution"
+    - "'proposed' not in error_on_name_resolution"
+    - "'filter_string' not in error_on_name_resolution"
+
+- name: Error when required parameter is missing
+  aci_rest:
+    host: '{{ aci_hostname }}'
+    username: '{{ aci_username }}'
+    password: '{{ aci_password }}'
+    validate_certs: '{{ aci_validate_certs | default(false) }}'
+    use_ssl: '{{ aci_use_ssl | default(true) }}'
+    use_proxy: '{{ aci_use_proxy | default(true) }}'
+    output_level: debug
+    method: post
+    content:
+      fvTenant:
+        attributes:
+          name: ansible_test
+  ignore_errors: yes
+  register: error_on_missing_required_param
+
+- name: Verify error_on_missing_required_param
+  assert:
+    that:
+    - error_on_missing_required_param.failed == true
+    - 'error_on_missing_required_param.msg == "missing required arguments: path"'
+    - "'current' not in error_on_missing_required_param"
+    - "'previous' not in error_on_missing_required_param"
+    - "'sent' not in error_on_missing_required_param"
+    - "'proposed' not in error_on_missing_required_param"
+    - "'filter_string' not in error_on_missing_required_param"
+
+- name: Error when attributes are missing
+  aci_rest:
+    host: '{{ aci_hostname }}'
+    username: '{{ aci_username }}'
+    password: '{{ aci_password }}'
+    validate_certs: '{{ aci_validate_certs | default(false) }}'
+    use_ssl: '{{ aci_use_ssl | default(true) }}'
+    use_proxy: '{{ aci_use_proxy | default(true) }}'
+    output_level: debug
+    path: /api/mo/uni/tn-ansible_test.json
+    method: post
+    content:
+      fvTenant:
+        children:
+  ignore_errors: yes
+  register: error_on_missing_attributes
+
+- name: Verify error_on_missing_attributes
+  assert:
+    that:
+    - error_on_missing_attributes.failed == true
+    - error_on_missing_attributes.method == 'POST'
+    - "error_on_missing_attributes.msg == 'APIC Error 400: invalid data at line \\'1\\'. Attributes are missing, tag \\'attributes\\' must be specified first, before any other tag'"
+    - 'error_on_missing_attributes.response == "HTTP Error 400: Bad Request"'
+    - error_on_missing_attributes.status == 400
+    - error_on_missing_attributes.url == 'https://sandboxapicdc.cisco.com/api/mo/uni/tn-ansible_test.json?rsp-subtree=modified'
+    - "'current' not in error_on_missing_attributes"
+    - "'previous' not in error_on_missing_attributes"
+    - "'sent' not in error_on_missing_attributes"
+    - "'proposed' not in error_on_missing_attributes"
+    - "'filter_string' not in error_on_missing_attributes"
+
+- name: Error when input does not validate
+  aci_rest:
+    host: '{{ aci_hostname }}'
+    username: '{{ aci_username }}'
+    password: '{{ aci_password }}'
+    validate_certs: '{{ aci_validate_certs | default(false) }}'
+    use_ssl: '{{ aci_use_ssl | default(true) }}'
+    use_proxy: '{{ aci_use_proxy | default(true) }}'
+    output_level: debug
+    path: /api/mo/uni.json
+    method: post
+    content:
+      fvTenant:
+        attributes:
+          name: ansible_test
+          descr: This is an [invalid] description
+  ignore_errors: yes
+  register: error_on_input_validation
+
+- name: Verify error_on_input_validation
+  assert:
+    that:
+    - error_on_input_validation.failed == true
+    - error_on_input_validation.method == 'POST'
+    - "error_on_input_validation.msg == 'APIC Error 801: property descr of uni/tn-ansible_test failed validation for value \\'This is an [invalid] description\\''"
+    - 'error_on_input_validation.response == "HTTP Error 400: Bad Request"'
+    - error_on_input_validation.status == 400
+    - error_on_input_validation.url == 'https://sandboxapicdc.cisco.com/api/mo/uni.json?rsp-subtree=modified'
+    - "'current' not in error_on_input_validation"
+    - "'previous' not in error_on_input_validation"
+    - "'sent' not in error_on_input_validation"
+    - "'proposed' not in error_on_input_validation"
+    - "'filter_string' not in error_on_input_validation"
+
+- name: Error when invalid attributes are used
+  aci_rest:
+    host: '{{ aci_hostname }}'
+    username: '{{ aci_username }}'
+    password: '{{ aci_password }}'
+    validate_certs: '{{ aci_validate_certs | default(false) }}'
+    use_ssl: '{{ aci_use_ssl | default(true) }}'
+    use_proxy: '{{ aci_use_proxy | default(true) }}'
+    output_level: debug
+    path: /api/mo/uni.json
+    method: post
+    content:
+      fvTenant:
+        attributes:
+          name: ansible_test
+          description: This is an "invalid" description
+  ignore_errors: yes
+  register: error_on_invalid_attributes
+
+- name: Verify error_on_invalid_attributes
+  assert:
+    that:
+    - error_on_invalid_attributes.failed == true
+    - error_on_invalid_attributes.method == 'POST'
+    - "error_on_invalid_attributes.msg == 'APIC Error 400: unknown attribute \\'description\\' in element \\'fvTenant\\''"
+    - 'error_on_invalid_attributes.response == "HTTP Error 400: Bad Request"'
+    - error_on_invalid_attributes.status == 400
+    - error_on_invalid_attributes.url == 'https://sandboxapicdc.cisco.com/api/mo/uni.json?rsp-subtree=modified'
+    - "'current' not in error_on_invalid_attributes"
+    - "'previous' not in error_on_invalid_attributes"
+    - "'sent' not in error_on_invalid_attributes"
+    - "'proposed' not in error_on_invalid_attributes"
+    - "'filter_string' not in error_on_invalid_attributes"
+
+- name: Error on invalid object
+  aci_rest:
+    host: '{{ aci_hostname }}'
+    username: '{{ aci_username }}'
+    password: '{{ aci_password }}'
+    validate_certs: '{{ aci_validate_certs | default(false) }}'
+    use_ssl: '{{ aci_use_ssl | default(true) }}'
+    use_proxy: '{{ aci_use_proxy | default(true) }}'
+    output_level: debug
+    path: /api/mo/uni.json
+    method: post
+    content:
+      fvFoobar:
+        attributes:
+          name: ansible_test
+  ignore_errors: yes
+  register: error_on_invalid_object
+
+- name: Verify error_on_invalid_object
+  assert:
+    that:
+    - error_on_invalid_object.failed == true
+    - error_on_invalid_object.method == 'POST'
+    - "error_on_invalid_object.msg == 'APIC Error 122: unknown managed object class fvFoobar'"
+    - 'error_on_invalid_object.response == "HTTP Error 400: Bad Request"'
+    - error_on_invalid_object.status == 400
+    - error_on_invalid_object.url == 'https://sandboxapicdc.cisco.com/api/mo/uni.json?rsp-subtree=modified'
+    - "'current' not in error_on_invalid_object"
+    - "'previous' not in error_on_invalid_object"
+    - "'sent' not in error_on_invalid_object"
+    - "'proposed' not in error_on_invalid_object"
diff --git a/test/integration/targets/aci_rest/tasks/json_inline.yml b/test/integration/targets/aci_rest/tasks/json_inline.yml
index fec7f4f290..86c48d43a3 100644
--- a/test/integration/targets/aci_rest/tasks/json_inline.yml
+++ b/test/integration/targets/aci_rest/tasks/json_inline.yml
@@ -1,12 +1,8 @@
 # Test code for the ACI modules
-# Copyright 2017, Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
 
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-- name: Test that we have an ACI APIC host, ACI username and ACI password
-  fail:
-    msg: 'Please define the following variables: aci_hostname, aci_username and aci_password.'
-  when: aci_hostname is not defined or aci_username is not defined or aci_password is not defined
 
 # CLEAN ENVIRONMENT
 - name: Remove tenant
@@ -19,7 +15,6 @@
     use_proxy: '{{ aci_use_proxy | default(true) }}'
     path: /api/mo/uni/tn-[ansible_test].json
     method: delete
-  delegate_to: localhost
 
 # ADD TENANT
 - name: Add tenant (normal mode)
diff --git a/test/integration/targets/aci_rest/tasks/json_string.yml b/test/integration/targets/aci_rest/tasks/json_string.yml
index 2c7e5622fa..a05f53bddb 100644
--- a/test/integration/targets/aci_rest/tasks/json_string.yml
+++ b/test/integration/targets/aci_rest/tasks/json_string.yml
@@ -1,12 +1,8 @@
 # Test code for the ACI modules
-# Copyright 2017, Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
 
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-- name: Test that we have an ACI APIC host, ACI username and ACI password
-  fail:
-    msg: 'Please define the following variables: aci_hostname, aci_username and aci_password.'
-  when: aci_hostname is not defined or aci_username is not defined or aci_password is not defined
 
 # CLEAN ENVIRONMENT
 - name: Remove tenant
diff --git a/test/integration/targets/aci_rest/tasks/main.yml b/test/integration/targets/aci_rest/tasks/main.yml
index 940b66760f..c7f7f20e9d 100644
--- a/test/integration/targets/aci_rest/tasks/main.yml
+++ b/test/integration/targets/aci_rest/tasks/main.yml
@@ -1,8 +1,13 @@
 # Test code for the ACI modules
-# Copyright 2017, Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
 
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
+- name: Test that we have an ACI APIC host, ACI username and ACI password
+  fail:
+    msg: 'Please define the following variables: aci_hostname, aci_username and aci_password.'
+  when: aci_hostname is not defined or aci_username is not defined or aci_password is not defined
+
 - include_tasks: yaml_inline.yml
   tags: yaml_inline
 
@@ -17,3 +22,6 @@
 
 - include_tasks: xml_string.yml
   tags: xml_string
+
+- include_tasks: error_handling.yml
+  tags: error_handling
diff --git a/test/integration/targets/aci_rest/tasks/xml_string.yml b/test/integration/targets/aci_rest/tasks/xml_string.yml
index b2c304e5e1..de31f5dd32 100644
--- a/test/integration/targets/aci_rest/tasks/xml_string.yml
+++ b/test/integration/targets/aci_rest/tasks/xml_string.yml
@@ -1,12 +1,8 @@
 # Test code for the ACI modules
-# Copyright 2017, Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
 
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-- name: Test that we have an ACI APIC host, ACI username and ACI password
-  fail:
-    msg: 'Please define the following variables: aci_hostname, aci_username and aci_password.'
-  when: aci_hostname is not defined or aci_username is not defined or aci_password is not defined
 
 # CLEAN ENVIRONMENT
 - name: Remove tenant
diff --git a/test/integration/targets/aci_rest/tasks/yaml_inline.yml b/test/integration/targets/aci_rest/tasks/yaml_inline.yml
index 96ae3b6aba..a8fbf8801d 100644
--- a/test/integration/targets/aci_rest/tasks/yaml_inline.yml
+++ b/test/integration/targets/aci_rest/tasks/yaml_inline.yml
@@ -1,12 +1,8 @@
 # Test code for the ACI modules
-# Copyright 2017, Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
 
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-- name: Test that we have an ACI APIC host, ACI username and ACI password
-  fail:
-    msg: 'Please define the following variables: aci_hostname, aci_username and aci_password.'
-  when: aci_hostname is not defined or aci_username is not defined or aci_password is not defined
 
 # CLEAN ENVIRONMENT
 - name: Remove tenant
diff --git a/test/integration/targets/aci_rest/tasks/yaml_string.yml b/test/integration/targets/aci_rest/tasks/yaml_string.yml
index ceaa4f7271..ca67eb5f4c 100644
--- a/test/integration/targets/aci_rest/tasks/yaml_string.yml
+++ b/test/integration/targets/aci_rest/tasks/yaml_string.yml
@@ -1,12 +1,8 @@
 # Test code for the ACI modules
-# Copyright 2017, Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
 
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-- name: Test that we have an ACI APIC host, ACI username and ACI password
-  fail:
-    msg: 'Please define the following variables: aci_hostname, aci_username and aci_password.'
-  when: aci_hostname is not defined or aci_username is not defined or aci_password is not defined
 
 # CLEAN ENVIRONMENT
 - name: Remove tenant