adding a new file DOCS.md (same as https://github.com/pelias/api/wiki/API-Endpoints), modifying controller/index.js to return text/html instead of application/json by default. Using markdown module to convert MD to HTML. Fixing tests (removed test/jsonp.coffee)

DOCS.md

@@ -0,0 +1,53 @@
+## /suggest
+* this is the autocomplete endpoint (fast response time/ straight from the memory)
+* takes the following params
+  * **input**: query string (required)
+  * **lat**: latitude from where you are searching (required)
+  * **lon**: longitude (required)
+  * **zoom**: zoom level at which you are viewing the world (optional)
+  * **size**: number of results you need (optional, defaults to 10)
+  * **layers**: datasets you want to query upon (optional, defaults to ```poi,admin,address```). It can be ```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```
+    * or it can also be specific to one particular dataset for example: ```geoname```
+* Lat/Lon is **required** currently because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444)
+
+## /suggest/coarse
+* Only queries the admin layers
+* Its the same as ```/suggest``` with layers param set to ```admin```
+* ```/suggest/coarse``` takes all other params that ```/suggest``` takes
+
+## /search
+* this is the full text search endpoint (looks up elasticsearch doc store, slightly slower than suggest)
+* takes the following params (same as suggest)
+  * **input** (required)
+  * **lat** (optional)
+  * **lon** (optional)
+  * **zoom** (optional)
+  * **bbox**: (optional) the bounding box where you want all your results to appear and be contained within that bbox. it can be one of the following comma separated string (they are all different ways of saying the same thing)
+    * bottom_left lat, bottom_left lon, top_right lat, top_right lon
+    * left,bottom,right,top
+    * min Longitude , min Latitude , max Longitude , max Latitude 
+  * **size** (optional, defaults to 10)
+  * **layers** (optional, defaults to ```poi,admin,address```)
+
+## /search/coarse
+* Similar to its suggest counterpart 
+* Its /search with layers param set to ```admin```
+* ```/search/coarse``` takes all other params that /search takes
+
+## /reverse
+* Does reverse geocoding
+* It takes the following params
+  * **lat** (required)
+  * **lon** (required)
+  * **zoom** (optional)
+  * **bbox** (optional)
+  * **layers** (optional, defaults to ```poi,admin,address```)
+
+## /doc
+* retrieve a document or multiple documents at once
+* it takes just one param
+  * **id**: (required) unique id of the document that need 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

controller/index.js

@@ -1,10 +1,21 @@
 
 var pkg = require('../package');
+var markdown = require('markdown').markdown;
+var fs = require('fs');
 
 function setup(){
 
   function controller( req, res, next ){
 
+    fs.readFile('./DOCS.md', 'utf8', function (err, content) {
+      if (!err) {
+        var header = '# Pelias API\n';
+        var version = '### Version: ['+ pkg.version+ '](https://github.com/pelias/api/releases)\n';
+        var style = '<style>html{font-family:monospace}</style>';
+        
+        res.send(style + markdown.toHTML(header + version + content));
+
+      } else {
         // stats
         res.json({
           name: pkg.name,
@@ -12,6 +23,9 @@ function setup(){
             number: pkg.version
           }
         });
+      }
+      
+    });
 
   }
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "pelias-api",
   "author": "mapzen",
-  "version": "0.0.0",
+  "version": "1.1.7",
   "description": "Pelias API",
   "homepage": "https://github.com/pelias/api",
   "license": "MIT",
@@ -39,7 +39,8 @@
     "geopipes-elasticsearch-backend": "0.0.12",
     "pelias-suggester-pipeline": "2.0.2",
     "is-object": "^1.0.1",
-    "pelias-esclient": "0.0.25"
+    "pelias-esclient": "0.0.25",
+    "markdown": "0.5.0"
   },
   "devDependencies": {
     "ciao": "^0.3.4",

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

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(';

test/unit/controller/index.js

@@ -20,6 +20,10 @@ module.exports.tests.info = function(test, common) {
       t.equal(typeof json.version, 'object', 'version');
       t.equal(typeof json.version.number, 'string', 'version number');
       t.end();
+    },
+      send: function( html ){
+      t.equal(typeof html, 'string', 'returns string');
+      t.end();
     }};
     controller( null, res );
   });