Merge pull request #108 from pelias/better-index-page

Better API index page
10 years ago · ffc19457a4
6 changed files with 179 additions and 31 deletions
--- a/DOCS.md
+++ b/DOCS.md
@ -0,0 +1,114 @@
+## /search
+
+Full text search endpoint which queries the elasticsearch doc store, slightly slower than suggest.
+
+#### Required Parameters
+* **input**: query string
+
+#### Optional Parameters
+* **lat**: latitude
+* **lon**: longitude
+* **zoom**: zoom level from which you wish to view the world
+* **size**: number of results requested (defaults to 10)
+* **layers**: datasets you wish to query (defaults to ```poi,admin,address```). 
+  * valid values are ```poi```, ```admin``` or ```address``` 
+    * ```poi``` expands internally to ```geoname```, ```osmnode```, ```osmway``` 
+    * ```admin``` expands to ```admin0```, ```admin1```, ```admin2```, ```neighborhood```, ```locality```, ```local_admin```
+    * ```address``` expands to ```osmaddress```, ```openaddresses```
+  * can also be specific to one particular dataset, for example ```geoname```
+* **bbox**: the bounding box from which you want all your results to come
+  * can be one of the following comma separated string values
+    * bottom left lat, bottom left lon, top right lat, top right lon
+    * left, bottom, right, top
+    * min longitude, min latitude, max longitude, max latitude 
+
+
+## /search/coarse
+
+This is a coarse forward geocoder endpoint which only searches admin dataset layers.
+
+#### Required Parameters
+* **input**: query string
+
+#### Optional Parameters
+* **lat**: latitude
+* **lon**: longitude
+* **zoom**: zoom level from which you wish to view the world
+* **bbox**: the bounding box frome which you want all your results to come
+* **size**: (defaults to 10)
+* **layers**: (defaults to ```admin```)
+
+
+## /suggest
+
+The autocomplete endpoint, it offers fast response time. Mixes results from around the provided lat/lon and also from precision level 1 and 3.
+
+#### Required Parameters
+* **input**: query string
+* **lat**: latitude
+* **lon**: longitude
+  * lat/lon are **required** currently because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444)
+
+#### Optional Parameters
+* **zoom**: zoom level from which you wish to view the world
+* **size**: number of results requested (defaults to 10)
+* **layers**: datasets you wish to query (defaults to ```poi,admin,address```)
+
+
+## /suggest/coarse
+
+Only queries the admin layers.
+
+#### Required Parameters
+* **input**: query string
+* **lat**: latitude from where you are searching
+* **lon**: longitude
+  * lat/lon are **required** currently because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444)
+
+#### Optional Parameters
+* **zoom**: zoom level from which you wish to view the world
+* **size**: number of results requested (defaults to 10)
+* **layers**: datasets you wish to query (defaults to ```admin```)
+
+
+## /suggest/nearby
+
+Works as autocomplete for places located near a latitude/longitude, this endpoint is the same as ```/suggest``` but the results are all from within 50 kilometers of the specified point.  Unlike ```/suggest```, ```/suggest/nearby``` does not mix results from different precision levels (500km, 1000km etc from lat/lon).
+
+#### Required Parameters
+* **input**: query string
+* **lat**: latitude
+* **lon**: longitude
+  * lat/lon are **required** currently because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444)
+
+#### Optional Parameters
+* **zoom**: zoom level from which you wish to view the world
+* **size**: number of results you need (defaults to 10)
+* **layers**: datasets you wish to query (defaults to ```poi,admin,address```)
+
+
+## /reverse
+
+Reverse geocoding endpoint.
+
+#### Required Parameters
+* **lat**: latitude
+* **lon**: longitude
+
+#### Optional Parameters
+* **zoom**: zoom level from which you wish to view the world
+* **bbox**: bounding box
+* **layers**: (defaults to ```poi,admin,address```)
+
+
+## /doc
+
+Retrieves a document or multiple documents at once.
+
+#### Required Parameters
+* one of **id** or **ids**
+  * **id**:
+    * unique id of the document to be retrieved
+    * should be in the form of type:id, for example: ```geoname:4163334```
+  * **ids**:
+    * if multiple docs are to be fetched in bulk, an array of ids
--- a/controller/index.js
+++ b/controller/index.js
@ -1,22 +1,31 @@

 var pkg = require('../package');
+var markdown = require('markdown').markdown;
+var fs = require('fs');

 function setup(){

-  function controller( req, res, next ){
-
-    // stats
+  var styleString = '<style>html{font-family:monospace}</style>';
+  var text = '# Pelias API\n';
+  text += '### Version: ['+ pkg.version+ '](https://github.com/pelias/api/releases)\n';
+  text += fs.readFileSync( './DOCS.md', 'utf8');
+  var indexHtml = styleString + markdown.toHTML(text);
+
+  function controller( req, res, next ) {
+    if (req.accepts('html')) {
+      res.send(indexHtml);
+      return;
+    }
+    // default behaviour
    res.json({
      name: pkg.name,
      version: {
        number: pkg.version
      }
    });
-
  }

  return controller;
-
 }

-module.exports = setup;
+module.exports = setup;
--- a/package.json
+++ b/package.json
@ -1,14 +1,14 @@
 {
  "name": "pelias-api",
  "author": "mapzen",
-  "version": "0.0.0",
+  "version": "1.1.7",
  "description": "Pelias API",
  "homepage": "https://github.com/pelias/api",
  "license": "MIT",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
-    "test": "npm run unit && npm run ciao",
+    "test": "npm run unit",
    "unit": "node test/unit/run.js | tap-spec",
    "ciao": "node node_modules/ciao/bin/ciao -c test/ciao.json test/ciao",
    "audit": "npm shrinkwrap; node node_modules/nsp/bin/nspCLI.js audit-shrinkwrap; rm npm-shrinkwrap.json;",
@ -37,16 +37,18 @@
    "geojson": "^0.2.0",
    "geojson-extent": "^0.3.1",
    "geopipes-elasticsearch-backend": "0.0.12",
-    "pelias-suggester-pipeline": "2.0.2",
    "is-object": "^1.0.1",
-    "pelias-esclient": "0.0.25"
+    "markdown": "0.5.0",
+    "pelias-esclient": "0.0.25",
+    "pelias-suggester-pipeline": "2.0.2"
  },
  "devDependencies": {
    "ciao": "^0.3.4",
    "jshint": "^2.5.6",
+    "nsp": "^0.3.0",
    "precommit-hook": "^1.0.7",
-    "tape": "^2.13.4",
+    "proxyquire": "^1.4.0",
    "tap-spec": "^0.2.0",
-    "nsp": "^0.3.0"
+    "tape": "^2.13.4"
  }
 }
--- a/test/ciao/index.coffee
+++ b/test/ciao/index.coffee
@ -6,7 +6,7 @@ path: '/'
 response.statusCode.should.equal 200

 #? content-type header correctly set
-response.should.have.header 'Content-Type','application/json; charset=utf-8'
+response.should.have.header 'Content-Type','text/html; charset=utf-8'

 #? charset header correctly set
 response.should.have.header 'Charset','utf8'
@ -20,8 +20,3 @@ response.headers.server.should.match /Pelias\/\d{1,2}\.\d{1,2}\.\d{1,2}/

 #? vanity header correctly set
 response.should.have.header 'X-Powered-By','mapzen'
-
-#? should respond in json with server info
-should.exist json
-should.exist json.name
-should.exist json.version
--- a/test/ciao/jsonp.coffee
+++ b/test/ciao/jsonp.coffee
@ -1,10 +0,0 @@
-
-#> jsonp
-path: '/?callback=test'
-
-#? content-type header correctly set
-response.should.have.header 'Content-Type','application/javascript; charset=utf-8'
-
-#? should respond with jsonp
-should.exist response.body
-response.body.substr(0,5).should.equal 'test(';
--- a/test/unit/controller/index.js
+++ b/test/unit/controller/index.js
@ -11,9 +11,15 @@ module.exports.tests.interface = function(test, common) {
  });
 };

-module.exports.tests.info = function(test, common) {
-  test('returns server info', function(t) {
+module.exports.tests.info_json = function(test, common) {
+  test('returns server info in json', function(t) {
    var controller = setup();
+    var req = {
+      accepts: function (format) {
+        t.equal(format, 'html', 'check for Accepts:html');
+        return false;
+      }
+    };
    var res = { json: function( json ){
      t.equal(typeof json, 'object', 'returns json');
      t.equal(typeof json.name, 'string', 'name');
@ -21,7 +27,39 @@ module.exports.tests.info = function(test, common) {
      t.equal(typeof json.version.number, 'string', 'version number');
      t.end();
    }};
-    controller( null, res );
+    controller( req, res );
+  });
+};
+
+module.exports.tests.info_html = function(test, common) {
+  test('returns server info in html', function(t) {
+
+    var style = '<style>html{font-family:monospace}</style>';
+    var mockText = 'this text should show up in the html content';
+    var fsMock = {
+      readFileSync: function (path, format) {
+        t.equal(path, './DOCS.md', 'open DOCS.md file');
+        t.equal(format, 'utf8', 'file format');
+        return mockText;
+      }
+    };
+
+    var proxyquire = require('proxyquire');
+    var setup = proxyquire('../../../controller/index', { 'fs': fsMock });
+
+    var controller = setup();
+    var req = {
+      accepts: function () {
+        return true;
+      }
+    };
+    var res = { send: function( content ){
+      t.equal(typeof content, 'string', 'returns string');
+      t.assert(content.indexOf(style) === 0, 'style set');
+      t.assert(content.indexOf(mockText) !== -1, 'file content added');
+      t.end();
+    }};
+    controller( req, res );
  });
 };