Adding instance -> custom_headers and instance -> api_path

changelogs/fragments/client_api_path.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - api - added custom headers and api path to the given request (https://github.com/ansible-collections/servicenow.itsm/pull/239).

plugins/doc_fragments/instance.py

@@ -48,6 +48,12 @@ class ModuleDocFragment(object):
         choices: [ 'password', 'refresh_token' ]
         type: str
         version_added: '1.1.0'
+      api_path:
+        description:
+          - Change the API endpoint of SNOW instance from default 'api/now'.
+        type: str
+        default: 'api/now'
+        version_added: '2.3.0'
       client_id:
         description:
           - ID of the client application used for OAuth authentication.
@@ -62,6 +68,11 @@ class ModuleDocFragment(object):
             variable will be used.
           - If provided, it requires I(client_id).
         type: str
+      custom_headers:
+        description:
+          - A dictionary containing any extra headers which will be passed with the request.
+        type: dict
+        version_added: '2.3.0'
       refresh_token:
         description:
           - Refresh token used for OAuth authentication.

plugins/module_utils/arguments.py

@@ -96,6 +96,10 @@
                 choices=["password", "refresh_token"],
                 fallback=(env_fallback, ["SN_GRANT_TYPE"]),
             ),
+            api_path=dict(
+                type="str",
+                default="api/now",
+            ),
             client_id=dict(
                 type="str",
                 fallback=(env_fallback, ["SN_CLIENT_ID"]),
@@ -105,6 +109,9 @@
                 no_log=True,
                 fallback=(env_fallback, ["SN_CLIENT_SECRET"]),
             ),
+            custom_headers=dict(
+                type="dict"
+            ),
             refresh_token=dict(
                 type="str",
                 no_log=True,

plugins/module_utils/attachment.py

@@ -14,13 +14,10 @@
 from . import errors
 
 
-def _path(*subpaths):
+def _path(api_path, *subpaths):
     return "/".join(
-        (
-            "api",
-            "now",
-            "attachment",
-        )
+        api_path
+        + ("attachment",)
         + subpaths
     )
 
@@ -41,7 +38,7 @@ def list_records(self, query=None):
 
         while offset < total:
             response = self.client.get(
-                _path(), query=dict(base_query, sysparm_offset=offset)
+                _path(self.client.api_path), query=dict(base_query, sysparm_offset=offset)
             )
 
             result.extend(response.json["result"])
@@ -55,7 +52,7 @@ def create_record(self, query, data, mime_type, check_mode):
             return query
         return self.client.request(
             "POST",
-            _path("file"),
+            _path(self.client.api_path, "file"),
             query=query,
             headers={"Accept": "application/json", "Content-type": mime_type},
             bytes=data,
@@ -88,7 +85,7 @@ def upload_records(self, table, table_sys_id, metadata_dict, check_mode):
 
     def delete_record(self, record, check_mode):
         if not check_mode:
-            self.client.delete(_path(record["sys_id"]))
+            self.client.delete(_path(self.client.api_path, record["sys_id"]))
 
     def delete_attached_records(self, table, table_sys_id, check_mode):
         for record in self.list_records(
@@ -111,8 +108,7 @@ def update_records(self, table, table_sys_id, metadata_dict, records, check_mode
         return list(mapped_records.values())
 
     def get_attachment(self, attachment_sys_id):
-        path = _path(attachment_sys_id, "file")
-        return self.client.get(path)
+        return self.client.get(_path(self.client.api_path, attachment_sys_id, "file"))
 
     def save_attachment(self, binary_data, dest):
         try:

plugins/module_utils/client.py

@@ -54,6 +54,8 @@ def __init__(
         access_token=None,
         client_id=None,
         client_secret=None,
+        custom_headers=None,
+        api_path="api/now",
         timeout=None,
         validate_certs=None,
     ):
@@ -70,6 +72,8 @@ def __init__(
         self.grant_type = "password" if grant_type is None else grant_type
         self.client_id = client_id
         self.client_secret = client_secret
+        self.custom_headers = custom_headers
+        self.api_path = tuple(api_path.strip("/").split("/"))
         self.refresh_token = refresh_token
         self.access_token = access_token
         self.timeout = timeout
@@ -172,6 +176,8 @@ def request(self, method, path, query=None, data=None, headers=None, bytes=None)
         if query:
             url = "{0}?{1}".format(url, urlencode(query))
         headers = dict(headers or DEFAULT_HEADERS, **self.auth_header)
+        if self.custom_headers:
+            headers = dict(headers, **self.custom_headers)
         if data is not None:
             data = json.dumps(data, separators=(",", ":"))
             headers["Content-type"] = "application/json"

plugins/module_utils/table.py

@@ -10,8 +10,8 @@
 from . import errors
 
 
-def _path(table, *subpaths):
-    return "/".join(("api", "now") + ("table", table) + subpaths)
+def _path(api_path, table, *subpaths):
+    return "/".join(api_path + ("table", table) + subpaths)
 
 
 def _query(original=None):
@@ -37,7 +37,7 @@ def list_records(self, table, query=None):
 
         while offset < total:
             response = self.client.get(
-                _path(table), query=dict(base_query, sysparm_offset=offset)
+                _path(self.client.api_path, table), query=dict(base_query, sysparm_offset=offset)
             )
 
             result.extend(response.json["result"])
@@ -64,7 +64,9 @@ def get_record(self, table, query, must_exist=False):
         return records[0] if records else None
 
     def get_record_by_sys_id(self, table, sys_id):
-        response = self.client.get(_path(table, sys_id))
+        response = self.client.get(
+            _path(self.client.api_path, table, sys_id)
+        )
         record = response.json["result"]
 
         return record
@@ -74,7 +76,7 @@ def create_record(self, table, payload, check_mode, query=None):
             # Approximate the result using the payload.
             return payload
 
-        return self.client.post(_path(table), payload, query=_query(query)).json[
+        return self.client.post(_path(self.client.api_path, table), payload, query=_query(query)).json[
             "result"
         ]
 
@@ -84,12 +86,12 @@ def update_record(self, table, record, payload, check_mode, query=None):
             return dict(record, **payload)
 
         return self.client.patch(
-            _path(table, record["sys_id"]), payload, query=_query(query)
+            _path(self.client.api_path, table, record["sys_id"]), payload, query=_query(query)
         ).json["result"]
 
     def delete_record(self, table, record, check_mode):
         if not check_mode:
-            self.client.delete(_path(table, record["sys_id"]))
+            self.client.delete(_path(self.client.api_path, table, record["sys_id"]))
 
 
 def find_user(table_client, user_id):

tests/unit/plugins/conftest.py

@@ -27,7 +27,9 @@
 
 @pytest.fixture
 def client(mocker):
-    return mocker.Mock(spec=Client)
+    return_client = mocker.Mock(spec=Client)
+    return_client.api_path = ("api", "now")
+    return return_client
 
 
 @pytest.fixture