Adding option to specify API version

GraceDB servers will soon have a versioned API, so this commit
allows the user to optionally select which API version they want
to talk to.  There is also a safeguard which checks whether the
specified API version is legitimate and available on the server
they are using.

ligo/gracedb/rest.py

@@ -381,20 +381,88 @@ class GraceDb(GsiRest):
     GraceDB behind a proxy. For other kwargs accepted by the constructor,
     consult the source code.
     """
-    def __init__(self, service_url=DEFAULT_SERVICE_URL,
-            proxy_host=None, proxy_port=3128, *args, **kwargs):
-        GsiRest.__init__(self, service_url, proxy_host, proxy_port, *args, **kwargs)
+    def __init__(self, service_url=DEFAULT_SERVICE_URL, proxy_host=None,
+            proxy_port=3128, api_version=None, *args, **kwargs):
+        super(GraceDb, self).__init__(service_url, proxy_host,
+            proxy_port, *args, **kwargs)
 
-        self.service_url = service_url
+        # Check version type
+        if api_version is not None and not isinstance(api_version,
+            six.string_types):
+            raise TypeError('api_version should be a string')
+
+        # Sets default and versioned service URLs
+        # (self._service_url, self._versioned_service_url)
+        self._set_service_url(service_url, api_version)
+
+        # Set version
+        self._api_version = api_version
+
+        # Set service_info to None, will be obtained from the server when
+        # the user takes an action which needs this information.
         self._service_info = None
 
+    def _set_service_url(self, service_url, api_version):
+        """Sets versioned and unversioned service URLs"""
+        # Make sure path ends with '/'
+        if not service_url.endswith('/'):
+            service_url += '/'
+
+        # Default service url (unversioned)
+        self._service_url = service_url
+
+        # Versioned service url (if version provided)
+        self._versioned_service_url = service_url
+        if api_version and api_version != 'default':
+            # If api_version is 'default', that is equivalent to not setting
+            # the version and indicates that the user wants to use the
+            # default/non-versioned API
+            self._versioned_service_url += (api_version + '/')
+
+    @property
+    def service_url(self):
+        # Will be removed in the future
+        print("DEPRECATED: this attribute has been moved to '_service_url'")
+        return self._service_url
+
     @property
     def service_info(self):
+        """Info from root of API. Should be a dict"""
         if not self._service_info:
-            r = self.request("GET", self.service_url)
+            # try-except block takes user-specified API version to use and
+            # checks whether that version is available on the server
+            try:
+                r = self.request("GET", self._versioned_service_url)
+            except HTTPError as e:
+                # If we get a 404 error, that means that the versioned
+                # service URL was not found. We assume that this happened
+                # because the user requested an unavailable API version.
+                if (e.status == 404):
+                    # Get versions from unversioned API root
+                    r = self.request("GET", self._service_url)
+                    available_api_versions = r.json().get('API_VERSIONS', None)
+                    if available_api_versions:
+                        err_msg = ('Bad API version. Available versions for '
+                            'this server are: {0}').format(
+                            available_api_versions)
+                    else:
+                        # Case where server doesn't have versions, for some
+                        # reason.
+                        err_msg = ('This server does not have a versioned API.'
+                            ' Reinstantiate your client without a version.')
+
+                    # Raise error
+                    raise ValueError(err_msg)
+                else:
+                    # Not a 404 error, must be something else
+                    raise e
             self._service_info = r.json()
         return self._service_info
 
+    @property
+    def api_versions(self):
+        return self.service_info.get('API_VERSIONS')
+
     @property
     def links(self):
         return self.service_info.get('links')
@@ -447,7 +515,7 @@ class GraceDb(GsiRest):
 
     def request(self, method, *args, **kwargs):
         if method.lower() in ['post', 'put']:
-            kwargs['priming_url'] = self.service_url
+            kwargs['priming_url'] = self._service_url
         return GsiRest.request(self, method, *args, **kwargs)
 
     def _getCode(self, input_value, code_dict):
@@ -1780,8 +1848,8 @@ class GraceDbBasic(GraceDb):
     GraceDB behind a proxy. For other kwargs accepted by the constructor,
     consult the source code.
     """
-    def __init__(self, service_url=DEFAULT_BASIC_SERVICE_URL,
-            proxy_host=None, proxy_port=3128, username=None, password=None,
+    def __init__(self, service_url=DEFAULT_BASIC_SERVICE_URL, proxy_host=None,
+            proxy_port=3128, username=None, password=None, api_version=None,
             *args, **kwargs):
 
         o = urlparse(service_url)
@@ -1832,7 +1900,20 @@ class GraceDbBasic(GraceDb):
             else:
                 self.connector = lambda: six.moves.http_client.HTTPSConnection(host, port)
 
-        self.service_url = service_url
+        # Check version type
+        if api_version is not None and not isinstance(api_version,
+            six.string_types):
+            raise TypeError('api_version should be a string')
+
+        # Sets default and versioned service URLs
+        # (self._service_url, self._versioned_service_url)
+        self._set_service_url(service_url, api_version)
+
+        # Set version
+        self._api_version = api_version
+
+        # Set service_info to None, will be obtained from the server when
+        # the user takes an action which needs this information.
         self._service_info = None
 
     # When there is a problem with the SSL connection or authentication,

ligo/gracedb/test/test.py

@@ -86,7 +86,7 @@ class TestGraceDb(unittest.TestCase):
 
         # Set up client
         cls._gracedb = GraceDb(TEST_SERVICE)
-        print("Using service {0}".format(TEST_SERVICE))
+        print("Using service {0}".format(cls._gracedb._versioned_service_url))
 
 
 class TestMain(TestGraceDb):