Merge pull request #3495 from zeha/forjeeves

Add /api discovery endpoint

docs/markdown/httpapi/api_spec.md

@@ -96,14 +96,29 @@ Common Error Causes
 3. For requests that operate on a zone, the `zone_id` URL part was invalid. To get a valid `zone_id`, list the zones with the `/api/v1/servers/:server_id/zones` endpoint.
 
 
+URL: /api
+---------
+
+Version discovery endpoint.
+
+Allowed methods: `GET`
+
+    [
+      {
+        "url": "/api/v1",
+        "version": 1
+      }
+    ]
+
+
 URL: /api/v1
 ------------
 
 Allowed methods: `GET`
 
     {
       "server_url": "/api/v1/servers{/server}",
-      "api_features": [],
+      "api_features": []
     }
 
 **TODO**:

pdns/ws-api.cc

@@ -91,6 +91,22 @@ static Json getServerDetail() {
   };
 }
 
+/* Return information about the supported API versions.
+ * The format of this MUST NEVER CHANGE at it's not versioned.
+ */
+void apiDiscovery(HttpRequest* req, HttpResponse* resp) {
+  if(req->method != "GET")
+    throw HttpMethodNotAllowedException();
+
+  Json version1 = Json::object {
+    { "version", 1 },
+    { "url", "/api/v1" }
+  };
+  Json doc = Json::array { version1 };
+
+  resp->setBody(doc);
+}
+
 void apiServer(HttpRequest* req, HttpResponse* resp) {
   if(req->method != "GET")
     throw HttpMethodNotAllowedException();

pdns/ws-api.hh

@@ -25,6 +25,7 @@
 #include <map>
 #include "webserver.hh"
 
+void apiDiscovery(HttpRequest* req, HttpResponse* resp);
 void apiServer(HttpRequest* req, HttpResponse* resp);
 void apiServerDetail(HttpRequest* req, HttpResponse* resp);
 void apiServerConfig(HttpRequest* req, HttpResponse* resp);

pdns/ws-auth.cc

@@ -1211,6 +1211,7 @@ void AuthWebServer::webThread()
       d_ws->registerApiHandler("/api/v1/servers/localhost/zones", &apiServerZones);
       d_ws->registerApiHandler("/api/v1/servers/localhost", &apiServerDetail);
       d_ws->registerApiHandler("/api/v1/servers", &apiServer);
+      d_ws->registerApiHandler("/api", &apiDiscovery);
     }
     d_ws->registerWebHandler("/style.css", boost::bind(&AuthWebServer::cssfunction, this, _1, _2));
     d_ws->registerWebHandler("/", boost::bind(&AuthWebServer::indexfunction, this, _1, _2));

pdns/ws-recursor.cc

@@ -426,6 +426,7 @@ RecursorWebServer::RecursorWebServer(FDMultiplexer* fdm)
   d_ws->registerApiHandler("/api/v1/servers/localhost/zones", &apiServerZones);
   d_ws->registerApiHandler("/api/v1/servers/localhost", &apiServerDetail);
   d_ws->registerApiHandler("/api/v1/servers", &apiServer);
+  d_ws->registerApiHandler("/api", &apiDiscovery);
 
   for(const auto& u : g_urlmap) 
     d_ws->registerWebHandler("/"+u.first, serveStuff);

regression-tests.api/test_Discovery.py

@@ -0,0 +1,10 @@
+from test_helper import ApiTestCase
+
+
+class DiscoveryTest(ApiTestCase):
+
+    def test_discovery(self):
+        r = self.session.get(self.url("/api"))
+        self.assert_success_json(r)
+        lst = r.json()
+        self.assertEquals(lst, [{'version': 1, 'url': '/api/v1'}])