Version the api (#226)

Moves all routes from `/api/*` to `/api/v1/*`. The exception is the
health check which remains at `/api/health`. I *think* this makes sense
because:
- The health check is unauthenticated
- The health check is not (normally) user facing
- The health check is unlikely to change much in api, and its use is
mostly related to deployment setups, (e.g. our helm chart), so we have
some flexibility here.

dask-gateway-server/dask_gateway_server/proxy/core.py

@@ -202,7 +202,7 @@ def get_start_command(self, is_child_process=True):
             "-tcp-address",
             self.tcp_address,
             "-api-url",
-            self.gateway_url + "/api/routes",
+            self.gateway_url + "/api/v1/routes",
             "-log-level",
             self.log_level,
         ]
@@ -284,7 +284,7 @@ async def setup(self, app):
 
         app.on_shutdown.append(self._on_shutdown)
 
-        app.add_routes([web.get("/api/routes", self.routes_handler)])
+        app.add_routes([web.get("/api/v1/routes", self.routes_handler)])
 
         # Proxy through the gateway application
         await self.add_route(kind="PATH", path="/", target=self.gateway_url)

dask-gateway-server/dask_gateway_server/routes.py

@@ -78,7 +78,7 @@ async def health(request):
     return web.json_response(health, status=status)
 
 
-@default_routes.get("/api/options")
+@default_routes.get("/api/v1/options")
 @api_handler(user_authenticated=True)
 async def cluster_options(request):
     user = request["user"]
@@ -88,7 +88,7 @@ async def cluster_options(request):
     return web.json_response({"cluster_options": spec})
 
 
-@default_routes.get("/api/clusters/")
+@default_routes.get("/api/v1/clusters/")
 @api_handler(user_authenticated=True)
 async def list_clusters(request):
     user = request["user"]
@@ -105,7 +105,7 @@ async def list_clusters(request):
     return web.json_response({c.name: c.to_dict() for c in clusters})
 
 
-@default_routes.post("/api/clusters/")
+@default_routes.post("/api/v1/clusters/")
 @api_handler(user_authenticated=True)
 async def create_cluster(request):
     user = request["user"]
@@ -136,7 +136,7 @@ def _parse_query_flag(val):
             return False
 
 
-@default_routes.get("/api/clusters/{cluster_name}")
+@default_routes.get("/api/v1/clusters/{cluster_name}")
 @api_handler(user_authenticated=True)
 async def get_cluster(request):
     user = request["user"]
@@ -154,7 +154,7 @@ async def get_cluster(request):
     return web.json_response(cluster.to_dict())
 
 
-@default_routes.delete("/api/clusters/{cluster_name}")
+@default_routes.delete("/api/v1/clusters/{cluster_name}")
 @api_handler(user_authenticated=True, token_authenticated=True)
 async def delete_cluster(request):
     user = request["user"]
@@ -170,7 +170,7 @@ async def delete_cluster(request):
     return web.Response(status=204)
 
 
-@default_routes.post("/api/clusters/{cluster_name}/scale")
+@default_routes.post("/api/v1/clusters/{cluster_name}/scale")
 @api_handler(user_authenticated=True)
 async def scale_cluster(request):
     user = request["user"]
@@ -200,7 +200,7 @@ async def scale_cluster(request):
     return web.Response()
 
 
-@default_routes.post("/api/clusters/{cluster_name}/adapt")
+@default_routes.post("/api/v1/clusters/{cluster_name}/adapt")
 @api_handler(user_authenticated=True)
 async def adapt_cluster(request):
     user = request["user"]
@@ -229,7 +229,7 @@ async def adapt_cluster(request):
     return web.Response()
 
 
-@default_routes.post("/api/clusters/{cluster_name}/heartbeat")
+@default_routes.post("/api/v1/clusters/{cluster_name}/heartbeat")
 @api_handler(token_authenticated=True)
 async def handle_heartbeat(request):
     backend = request.app["backend"]
@@ -239,7 +239,7 @@ async def handle_heartbeat(request):
     return web.Response()
 
 
-@default_routes.get("/api/clusters/{cluster_name}/addresses")
+@default_routes.get("/api/v1/clusters/{cluster_name}/addresses")
 @api_handler(token_authenticated=True)
 async def handle_addresses(request):
     cluster_name = request.match_info["cluster_name"]

dask-gateway/dask_gateway/client.py

@@ -408,7 +408,7 @@ async def _clusters(self, status=None):
         else:
             query = ""
 
-        url = "%s/api/clusters/%s" % (self.address, query)
+        url = "%s/api/v1/clusters/%s" % (self.address, query)
         resp = await self._request("GET", url)
         data = await resp.json()
         return [
@@ -451,7 +451,7 @@ def _config_cluster_options(self):
         return {k: format_template(v) for k, v in opts.items()}
 
     async def _cluster_options(self, use_local_defaults=True):
-        url = "%s/api/options" % self.address
+        url = "%s/api/v1/options" % self.address
         resp = await self._request("GET", url)
         data = await resp.json()
         options = Options._from_spec(data["cluster_options"])
@@ -478,7 +478,7 @@ def cluster_options(self, use_local_defaults=True, **kwargs):
         )
 
     async def _submit(self, cluster_options=None, **kwargs):
-        url = "%s/api/clusters/" % self.address
+        url = "%s/api/v1/clusters/" % self.address
         if cluster_options is not None:
             if not isinstance(cluster_options, Options):
                 raise TypeError(
@@ -519,7 +519,7 @@ def submit(self, cluster_options=None, **kwargs):
 
     async def _cluster_report(self, cluster_name, wait=False):
         params = "?wait" if wait else ""
-        url = "%s/api/clusters/%s%s" % (self.address, cluster_name, params)
+        url = "%s/api/v1/clusters/%s%s" % (self.address, cluster_name, params)
         resp = await self._request("GET", url)
         data = await resp.json()
         return ClusterReport._from_json(self._public_address, self.proxy_address, data)
@@ -606,7 +606,7 @@ def new_cluster(self, cluster_options=None, shutdown_on_close=True, **kwargs):
         )
 
     async def _stop_cluster(self, cluster_name):
-        url = "%s/api/clusters/%s" % (self.address, cluster_name)
+        url = "%s/api/v1/clusters/%s" % (self.address, cluster_name)
         await self._request("DELETE", url)
 
     def stop_cluster(self, cluster_name, **kwargs):
@@ -620,7 +620,7 @@ def stop_cluster(self, cluster_name, **kwargs):
         return self.sync(self._stop_cluster, cluster_name, **kwargs)
 
     async def _scale_cluster(self, cluster_name, n):
-        url = "%s/api/clusters/%s/scale" % (self.address, cluster_name)
+        url = "%s/api/v1/clusters/%s/scale" % (self.address, cluster_name)
         await self._request("POST", url, json={"count": n})
 
     def scale_cluster(self, cluster_name, n, **kwargs):
@@ -640,7 +640,7 @@ async def _adapt_cluster(
     ):
         await self._request(
             "POST",
-            "%s/api/clusters/%s/adapt" % (self.address, cluster_name),
+            "%s/api/v1/clusters/%s/adapt" % (self.address, cluster_name),
             json={"minimum": minimum, "maximum": maximum, "active": active},
         )
 

dask-gateway/dask_gateway/dask_cli.py

@@ -374,7 +374,7 @@ async def heartbeat(self, msg):
         client = AsyncHTTPClient()
         req = HTTPRequest(
             method="POST",
-            url=f"{self.api_url}/clusters/{self.cluster_name}/heartbeat",
+            url=f"{self.api_url}/v1/clusters/{self.cluster_name}/heartbeat",
             headers={
                 "Authorization": "token %s" % self.token,
                 "Content-type": "application/json",
@@ -385,15 +385,15 @@ async def heartbeat(self, msg):
 
     async def shutdown(self):
         client = AsyncHTTPClient()
-        url = "%s/clusters/%s" % (self.api_url, self.cluster_name)
+        url = f"{self.api_url}/v1/clusters/{self.cluster_name}"
         req = HTTPRequest(
             url, method="DELETE", headers={"Authorization": "token %s" % self.token}
         )
         await client.fetch(req)
 
     async def get_scheduler_address(self):
         client = AsyncHTTPClient()
-        url = "%s/clusters/%s/addresses" % (self.api_url, self.cluster_name)
+        url = f"{self.api_url}/v1/clusters/{self.cluster_name}/addresses"
         req = HTTPRequest(
             url, method="GET", headers={"Authorization": "token %s" % self.token}
         )

tests/test_cli.py

@@ -74,7 +74,7 @@ def mock_execle(*args):
         "-tcp-address",
         "127.0.0.1:8867",
         "-api-url",
-        "http://127.0.0.1:8888/api/routes",
+        "http://127.0.0.1:8888/api/v1/routes",
         "-log-level",
         "warn",
     ]