Allow to declare some versions as unsupported, and to provide an expl…

…icit message.

plugins/module_utils/_api_data.py

@@ -49,23 +49,31 @@ def __init__(self,
                     break
         self._current = None if self.needs_version else self.unversioned
 
+    def _select(self, data, api_version):
+        if data is None:
+            self._current = None
+            return False, None
+        if isinstance(data, str):
+            self._current = None
+            return False, data
+        self._current = data.specialize_for_version(api_version)
+        return self._current.fully_understood, None
+
     def provide_version(self, version):
         if not self.needs_version:
-            return self.unversioned.fully_understood
+            return self.unversioned.fully_understood, None
         api_version = LooseVersion(version)
         if self.unversioned is not None:
             self._current = self.unversioned.specialize_for_version(api_version)
-            return self._current.fully_understood
+            return self._current.fully_understood, None
         for other_version, comparator, data in self.versioned:
             if other_version == '*' and comparator == '*':
-                self._current = data.specialize_for_version(api_version)
-                return self._current.fully_understood
+                return self._select(data, api_version)
             other_api_version = LooseVersion(other_version)
             if _compare(api_version, other_api_version, comparator):
-                self._current = data.specialize_for_version(api_version)
-                return self._current.fully_understood
+                return self._select(data, api_version)
         self._current = None
-        return False
+        return False, None
 
     def get_data(self):
         if self._current is None:

plugins/modules/api_info.py

@@ -350,8 +350,12 @@ def main():
         module.fail_json(msg='Path /{path} is not yet supported'.format(path='/'.join(path)))
     if versioned_path_info.needs_version:
         api_version = get_api_version(api)
-        if not versioned_path_info.provide_version(api_version):
-            module.fail_json(msg='Path /{path} is not supported for API version {api_version}'.format(path='/'.join(path), api_version=api_version))
+        supported, not_supported_msg = versioned_path_info.provide_version(api_version)
+        if not supported:
+            msg = 'Path /{path} is not supported for API version {api_version}'.format(path='/'.join(path), api_version=api_version)
+            if not_supported_msg:
+                msg = '{0}: {1}'.format(msg, not_supported_msg)
+            module.fail_json(msg=msg)
     path_info = versioned_path_info.get_data()
 
     handle_disabled = module.params['handle_disabled']

plugins/modules/api_modify.py

@@ -1133,8 +1133,12 @@ def main():
     versioned_path_info = PATHS.get(tuple(path))
     if versioned_path_info.needs_version:
         api_version = get_api_version(api)
-        if not versioned_path_info.provide_version(api_version):
-            module.fail_json(msg='Path /{path} is not supported for API version {api_version}'.format(path='/'.join(path), api_version=api_version))
+        supported, not_supported_msg = versioned_path_info.provide_version(api_version)
+        if not supported:
+            msg = 'Path /{path} is not supported for API version {api_version}'.format(path='/'.join(path), api_version=api_version)
+            if not_supported_msg:
+                msg = '{0}: {1}'.format(msg, not_supported_msg)
+            module.fail_json(msg=msg)
     path_info = versioned_path_info.get_data()
 
     backend = get_backend(path_info)