feat: allow /v1 or /v2 prefixes in path

Signed-off-by: Adrien Barreau <adrien.barreau@ovhcloud.com>

Author: deathiop

README.rst

@@ -150,7 +150,6 @@ customer's information:
     print("Welcome", client.get('/me')['firstname'])
     print("Btw, your 'consumerKey' is '%s'" % validation['consumerKey'])
 
-
 Returned ``consumerKey`` should then be kept to avoid re-authenticating your
 end-user on each use.
 
@@ -414,6 +413,31 @@ Example usage:
 
     client = ovh.Client()
 
+Use v1 and v2 API versions
+--------------------------
+
+When using OVHcloud APIs (not So you Start or Kimsufi ones), you are given the
+opportunity to aim for two API versions. For the European API, for example:
+
+- the v1 is reachable through https://eu.api.ovh.com/v1
+- the v2 is reachable through https://eu.api.ovh.com/v2
+- the legacy URL is https://eu.api.ovh.com/1.0
+
+ Calling ``client.get``, you can target the API version you want:
+
+.. code:: python
+
+    client = ovh.Client(endpoint="ovh-eu")
+
+    # Call to https://eu.api.ovh.com/v1/xdsl/xdsl-yourservice
+    client.get("/v1/xdsl/xdsl-yourservice")
+
+    # Call to https://eu.api.ovh.com/v2/xdsl/xdsl-yourservice
+    client.get("/v2/xdsl/xdsl-yourservice")
+
+    # Legacy call to https://eu.api.ovh.com/1.0/xdsl/xdsl-yourservice
+    client.get("/xdsl/xdsl-yourservice")
+
 Custom configuration file
 -------------------------
 
@@ -425,7 +449,6 @@ Example usage:
 
     client = ovh.Client(config_file='/my/config.conf')
 
-
 Passing parameters
 ==================
 
@@ -495,8 +518,8 @@ Get the sources
     cd python-ovh
     python setup.py develop
 
-You've developed a new cool feature ? Fixed an annoying bug ? We'd be happy
-to hear from you !
+You've developed a new cool feature? Fixed an annoying bug? We'd be happy
+to hear from you!
 
 Run the tests
 -------------
@@ -510,7 +533,6 @@ note that we do not accept contributions with test coverage under 100%.
     pip install -e .[dev]
     pytest
 
-
 Build the documentation
 -----------------------
 

ovh/client.py

@@ -472,6 +472,20 @@ def call(self, method, path, data=None, need_auth=True):
         else:
             raise APIError(json_result.get("message"), response=result)
 
+    def _get_target(self, path):
+        """
+        _get_target returns the URL to target given an endpoint and a path.
+        If the path starts with `/v1` or `/v2`, then remove the trailing `/1.0` from the endpoint.
+
+        :param str path: path to use prefix from
+        :returns: target with one of /1.0 and /v1|2 path segment
+        :rtype: str
+        """
+        endpoint = self._endpoint
+        if endpoint.endswith("/1.0") and path.startswith(("/v1", "/v2")):
+            endpoint = endpoint[:-4]
+        return endpoint + path
+
     def raw_call(self, method, path, data=None, need_auth=True, headers=None):
         """
         Lowest level call helper. If ``consumer_key`` is not ``None``, inject
@@ -497,7 +511,7 @@ def raw_call(self, method, path, data=None, need_auth=True, headers=None):
                              the Content-Type header.
         """
         body = ""
-        target = self._endpoint + path
+        target = self._get_target(path)
 
         if headers is None:
             headers = {}

tests/test_client.py

@@ -275,3 +275,35 @@ def test_endpoints(self):
         for endpoint in ENDPOINTS.keys():
             auth_time = Client(endpoint).get("/auth/time", _need_auth=False)
             assert auth_time > 0
+
+    @mock.patch("time.time", return_value=1457018875.467238)
+    @mock.patch("ovh.client.Session.request")
+    @mock.patch("ovh.client.Client.time_delta", new_callable=mock.PropertyMock, return_value=0)
+    def test_version_in_url(self, m_time_delta, m_req, m_time):
+        m_res = m_req.return_value
+        m_res.status_code = 200
+
+        api = Client("ovh-eu", MockApplicationKey, MockApplicationSecret, MockConsumerKey)
+        api.call("GET", "/call", None, True)
+        api.call("GET", "/v1/call", None, True)
+        api.call("GET", "/v2/call", None, True)
+
+        signatures = {
+            "1.0": "$1$7f2db49253edfc41891023fcd1a54cf61db05fbb",
+            "v1": "$1$e6e7906d385eb28adcbfbe6b66c1528a42d741ad",
+            "v2": "$1$bb63b132a6f84ad5433d0c534d48d3f7c3804285",
+        }
+
+        def _h(prefix):
+            return {
+                "X-Ovh-Application": MockApplicationKey,
+                "X-Ovh-Consumer": MockConsumerKey,
+                "X-Ovh-Timestamp": str(MockTime),
+                "X-Ovh-Signature": signatures[prefix],
+            }
+
+        assert m_req.call_args_list == [
+            mock.call("GET", "https://eu.api.ovh.com/1.0/call", headers=_h("1.0"), data="", timeout=180),
+            mock.call("GET", "https://eu.api.ovh.com/v1/call", headers=_h("v1"), data="", timeout=180),
+            mock.call("GET", "https://eu.api.ovh.com/v2/call", headers=_h("v2"), data="", timeout=180),
+        ]