[api] Finish on beta-API

Author: GochoMugo

CHANGELOG.md

@@ -5,6 +5,14 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased][Unreleased]
 
+Added:
+
+* Expose API
+
+Changed:
+
+* [maintenance] Update all dependencies
+
 
 ## [0.3.0][0.3.0] - 2016-06-16
 

docs/api.md

@@ -0,0 +1,110 @@
+# API Documentation
+
+This API is useful for developers who:
+
+  * need a central repository of data on the charges of mobile
+    money transactions, and/or
+  * do not wish to re-implement cost calculation and their applications
+    can rely on network connectivity for this functionality
+
+
+## Introduction:
+
+The **Base URLs** for the API are `http://mmtc.forfuture.co.ke/api`
+(Insecure but more permanent)
+and `https://mmtcke-forfutureco.rhcloud.com/api`
+(Secure but less permanent).
+
+API Characteristics:
+
+  * **JSON**: data back-and-forth is formatted in JSON
+  * **Status codes**: responses are sent back with sensible status codes
+  * **Unauthenticated**: no authentication token is required, currently
+
+### Errors:
+
+When the response's status code is **not** 2xx, expect the response
+in the following structure:
+
+```json
+{
+  "error": {
+    "message": "error message",
+    "name": "ErrorName",
+    "statusCode": 400
+  }
+}
+```
+
+
+### Endpoints:
+
+* [GET /networks](#get-networks)
+* [GET /networks/:network](#get-networks-network)
+* [POST /cost](#post-cost)
+
+
+---
+<a href="#get-networks" name="get-networks"># <i class="fa fa-file-text"></i></a>
+
+```http
+GET /networks
+```
+
+Retrieve data for all networks. This is basically an amalgamation of the
+[data files][data-files].
+
+Example partial response:
+
+```http
+200 OK
+```
+
+```json
+{
+  "networks": [ /* CONTENT of each of the data files */ ]
+}
+```
+
+
+---
+<a href="#get-networks-network" name="get-networks-network"># <i class="fa fa-file-text"></i></a>
+
+```http
+GET /networks/:network
+```
+
+Retrieve data for `network`. This basically returns the content of
+the data file for `network`.
+
+
+---
+<a href="#post-cost" name="post-cost"># <i class="fa fa-file-text"></i></a>
+
+```http
+POST /cost
+```
+
+Perform a calculation.
+
+**Parameters:**
+
+* **network**: (Required) target network e.g. "mpesa"
+* **amount**: (Required) amount in transaction e.g. 2000
+* **transactionType**: (Required) type of transaction e.g. "transfer"
+* **transactor**: (Required) target transactor e.g. "agent"
+
+Example response:
+
+```http
+200 OK
+```
+
+```json
+{
+  "cost": 66
+}
+```
+
+
+[data-files]:https://github.com/forfuturellc/mmtc-ke/tree/master/data

docs/news.md

@@ -1,3 +1,15 @@
+<h2>Our API is open for developers <small>2016-09-01</h2>
+
+We have opened up our [API][api] for developers. It is intended to
+be used in applications that do **not** wish to re-implement
+calculations on money transactions.
+It is quite minimal and currently in development. We welcome
+contribution to improve it. Head over to our [Github repository][repo].
+
+[api]:/api/
+[repo]:https://github.com/forfuturellc/mmtc-ke
+
+
 <h2>Updated Terms and Conditions <small>2016-06-16</small></h2>
 
 We have updated our Terms and Conditions to reflect our change

engine/math.js

@@ -52,7 +52,7 @@ function calculate(name, params) {
 
   network = networks.getNetwork(name);
   if (!network) {
-    throw new errors.NetworkNotFound(`network '${name}' not found`);
+    throw new errors.NetworkNotFoundError(`network '${name}' not found`);
   }
 
   transaction = network.transactions.find(function(t) {

routes/api.js

@@ -12,12 +12,14 @@ const path = require('path');
 
 
 // npm-installed modules
+const _ = require('lodash');
 const Debug = require('debug');
 const express = require('express');
 
 
 // own modules
 const engine = require('../engine');
+const utils = require('./utils');
 
 
 // module variables
@@ -31,6 +33,13 @@ exports = module.exports = router;
 exports.router = router;
 
 
+// API doc
+router.get('/', function(req, res, next) {
+  const filepath = path.resolve(__dirname, '../docs/api.md');
+  return utils.renderMarkdownPage(req, res, next, filepath);
+});
+
+
 // serving data for all networks
 router.get('/networks', function(req, res, next) {
   return res.json({
@@ -51,13 +60,49 @@ router.get('/networks/:network', function(req, res, next) {
 });
 
 
+// calculations
+router.post('/cost', function(req, res, next) {
+  if (!_.isString(req.body.network)
+      || !_.isNumber(req.body.amount)
+      || !_.isString(req.body.transactionType)
+      || !_.isString(req.body.transactor)) {
+    const error = new Error('missing/invalid parameter');
+    error.statusCode = 400;
+    return next(error);
+  }
+
+  let cost;
+  try {
+    cost = engine.math.calculate(req.body.network, req.body);
+  } catch(ex) {
+    return next(ex);
+  }
+
+  return res.json({
+    cost,
+  });
+});
+
+
+// API 404
+router.use(function(req, res, next) {
+  const error = new Error('API Endpoint Not Found');
+  error.statusCode = 404;
+  return next(error);
+});
+
+
 // API Error handler
-router.use(function(err, req, res, next) {
-  err.statusCode = err.statusCode || 500;
-  if (err.statusCode === 500) {
-    logger.error(err);
+router.use(function(error, req, res, next) {
+  error.statusCode = error.statusCode || 500;
+  if (error.statusCode >= 500) {
+    logger.error(error);
   }
-  return res.status(err.statusCode).json({
-    error: err,
+  return res.status(error.statusCode).json({
+    error: {
+      message: error.message,
+      name: error.name,
+      statusCode: error.statusCode,
+    },
   });
 });

routes/public.js

@@ -128,30 +128,14 @@ router
 
 
 // News page
-router.get("/news", function(req, res, next) {
+router.get('/news', function(req, res, next) {
   const filepath = path.resolve(__dirname, '../docs/news.md');
-  return renderMarkdownPage(req, res, next, filepath);
+  return utils.renderMarkdownPage(req, res, next, filepath);
 });
 
 
 // Terms and conditions
-router.use('/tcs', function(req, res, next) {
+router.get('/tcs', function(req, res, next) {
   const filepath = path.resolve(__dirname, '../docs/terms-and-conditions.md');
-  return renderMarkdownPage(req, res, next, filepath);
+  return utils.renderMarkdownPage(req, res, next, filepath);
 });
-
-
-/**
- * Render a markdown page
- */
-function renderMarkdownPage(req, res, next, filepath) {
-  return engine.pages.getHTML(filepath, function(getErr, html) {
-    if (getErr) {
-      return next(getErr);
-    }
-
-    return utils.renderPage(req, res, 'misc/content', {
-      content: html,
-    });
-  });
-}

routes/utils.js

@@ -17,6 +17,15 @@ exports = module.exports = {
    * @param {Object} [ctx]
    */
   renderPage,
+  /**
+   * Render a markdown page
+   *
+   * @param  {Express.Request} req
+   * @param  {Express.Response} res
+   * @param  {Function} next
+   * @param  {String} filepath
+   */
+  renderMarkdownPage,
   /**
    * Web Middleware
    *
@@ -37,6 +46,10 @@ const config = require('config');
 const express = require('express');
 
 
+// own modules
+const engine = require("../engine");
+
+
 function webMiddleware(router, config) {
   if (!_.isPlainObject(config)) {
     throw new Error('expected configuration to be object');
@@ -59,3 +72,16 @@ function renderPage(req, res, path, ctx) {
   ctx.__path = req.path;
   return res.render(path, ctx);
 }
+
+
+function renderMarkdownPage(req, res, next, filepath) {
+  return engine.pages.getHTML(filepath, function(getErr, html) {
+    if (getErr) {
+      return next(getErr);
+    }
+
+    return renderPage(req, res, 'misc/content', {
+      content: html,
+    });
+  });
+}

web/_includes/head.html

@@ -8,6 +8,7 @@
 
   <link rel="stylesheet" href="{{ site.baseurl }}/static/bootstrap-themes/superhero.min.css">
   <link rel="stylesheet" href="{{ site.baseurl }}/vendor/animate.css/animate.min.css">
+  <link rel="stylesheet" href="{{ site.baseurl }}/vendor/font-awesome/css/font-awesome.min.css">
 
   {% set defaultCssURL = '/css/main.css' %}
   <link rel="stylesheet" href="{{ site.baseurl }}{{ cssURL or defaultCssURL }}">

web/_includes/header.html

@@ -22,6 +22,11 @@
               News
             </a>
           </li>
+          <li>
+            <a href="{{ site.baseurl }}/api/">
+              API
+            </a>
+          </li>
         </ul>
       </div><!--navbar-content-->
     </div>