From ea782c1cf2dc75e03ad4fd7bfe0b15a627682cd1 Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Fri, 13 May 2022 13:18:28 +0200
Subject: [PATCH] Add module defaults group community.routeros.api. (#90)

---
 changelogs/fragments/90-api-action-group.yml |  2 +
 docs/docsite/rst/api-guide.rst               | 41 ++++++++++++++++++--
 meta/runtime.yml                             |  4 ++
 3 files changed, 43 insertions(+), 4 deletions(-)
 create mode 100644 changelogs/fragments/90-api-action-group.yml

diff --git a/changelogs/fragments/90-api-action-group.yml b/changelogs/fragments/90-api-action-group.yml
new file mode 100644
index 0000000..23c748a
--- /dev/null
+++ b/changelogs/fragments/90-api-action-group.yml
@@ -0,0 +1,2 @@
+minor_changes:
+  - "Added a ``community.routeros.api`` module defaults group. Use with ``group/community.routeros.api`` to provide options for all API-based modules (https://github.com/ansible-collections/community.routeros/pull/89)."
diff --git a/docs/docsite/rst/api-guide.rst b/docs/docsite/rst/api-guide.rst
index 482af9a..bccdcfe 100644
--- a/docs/docsite/rst/api-guide.rst
+++ b/docs/docsite/rst/api-guide.rst
@@ -3,7 +3,7 @@
 How to connect to RouterOS devices with the RouterOS API
 ========================================================
 
-You can use the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` to connect to a RouterOS device with the RouterOS API.
+You can use the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` to connect to a RouterOS device with the RouterOS API. The :ref:`community.routeros.api_facts module <ansible_collections.community.routeros.api_facts_module>` allows to retrieve Ansible facts using the RouterOS API.
 
 No special setup is needed; the module needs to be run on a host that can connect to the device's API. The most common case is that the module is run on ``localhost``, either by using ``hosts: localhost`` in the playbook, or by using ``delegate_to: localhost`` for the task. The following example shows how to run the equivalent of ``/ip address print``:
 
@@ -33,9 +33,9 @@ No special setup is needed; the module needs to be run on a host that can connec
             # ca_path: /path/to/ca-certificate.pem
           register: print_path
 
-    - name: Show IP address of first interface
-      debug:
-        msg: "{{ print_path.msg[0].address }}"
+        - name: Show IP address of first interface
+          ansible.builtin.debug:
+            msg: "{{ print_path.msg[0].address }}"
 
 This results in the following output:
 
@@ -56,6 +56,39 @@ This results in the following output:
 
 Check out the documenation of the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` for details on the options.
 
+Using the ``community.routeros.api`` module defaults group
+----------------------------------------------------------
+
+To avoid having to specify common parameters for the :ref:`community.routeros.api module <ansible_collections.community.routeros.api_module>` and :ref:`community.routeros.api_facts module <ansible_collections.community.routeros.api_facts_module>` in every task, you can use the ``community.routeros.api`` module defaults group:
+
+.. code-block:: yaml+jinja
+
+    ---
+    - name: RouterOS test with API
+      hosts: localhost
+      gather_facts: no
+      module_defaults:
+        group/community.routeros.api
+          hostname: 192.168.1.1
+          password: admin
+          username: test1234
+          # The following options configure TLS/SSL.
+          # Depending on your setup, these options need different values:
+          tls: true
+          validate_certs: true
+          validate_cert_hostname: true
+          # If you are using your own PKI, specify the path to your CA certificate here:
+          # ca_path: /path/to/ca-certificate.pem
+      tasks:
+        - name: Gather facts"
+          community.routeros.api_facts:
+
+        - name: Get "ip address print"
+          community.routeros.api:
+            path: "ip address"
+
+Here both tasks will use the options set for the module defaults group.
+
 Setting up encryption
 ---------------------
 
diff --git a/meta/runtime.yml b/meta/runtime.yml
index 2ee3c9f..17bc297 100644
--- a/meta/runtime.yml
+++ b/meta/runtime.yml
@@ -1,2 +1,6 @@
 ---
 requires_ansible: '>=2.9.10'
+action_groups:
+  api:
+  - api
+  - api_facts