feat: API improvements (#4806)

* Use moment.js to parse dates, with better error messaging for unparseable dates

* Oops fix a bug here

* Add logging for unparseable dates

* Output a better error

* * Re-enabled heap dumps
* Improved API documentation

CONTRIBUTING.md

@@ -20,7 +20,6 @@
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-
 # Contributing to cgm-remote-monitor
 
 [![Build Status][build-img]][build-url]
@@ -42,11 +41,17 @@
 [waffle]: https://waffle.io/nightscout/cgm-remote-monitor
 [progress-img]: https://badge.waffle.io/nightscout/cgm-remote-monitor.svg?label=in+progress&title=In+Progress
 
-## Design & new features
+## Installation for development
 
-If you intend to add a new feature, please allow the community to participate in the design process by creating an issue to discuss your design. For new features, the issue should describe what use cases the new feature intends to solve, or which existing use cases are being improved.
+Nightscout is a Node.js application. The basic installation of the software for local purposes is:
 
-Note Nighscout has a plugin architecture for adding new features. We expect most code for new features live inside a Plugin, so the code retains a clear separation of concerns. If the Plugin API doesn't implement all features you need to implement your feature, please discuss with us on adding those features to the API. Note new features should under almost no circumstances require changes to the existing plugins.
+1. Clone the software to your local machine using git
+2. Install Node from https://nodejs.org/en/download/
+2. Use `npm` to install Nightscout dependencies by invokin `npm install` in the project directory. Note the
+   dependency installation has to be done usign a non-root user - _do not use root_ for development and hosting
+   the software!
+3. Get a Mongo database by either installing Mongo locally, or get a free cloud account from mLab or Mongodb Atlas.
+4. Configure nightscout by copying `my.env.template` to `my.env` and run it - see the next chapter in the instructions
 
 ## Develop on `dev`
 
@@ -58,6 +63,23 @@ Once checked out, install the dependencies using `npm install`, then copy the in
 
 If you want to additionaly test the site in production mode, create a file called `my.prod.env` that's a copy of the dev file but with `NODE_ENV=production` and start the site using `npm run prod`.
 
+## REST API
+
+Nightscout implements a REST API for data syncronization. The API is documented using Swagger. To access the documentation
+for the API, run Nightscout locally and load the documentation from /api-docs (or read the associated swagger.json and swagger.yaml
+files locally).
+
+Note all dates used to access the API and dates stored in the objects are expected to comply with the ISO-8601 format and
+be deserializable by the Javascript Date class. Of note here is the dates can contain a plus sign which has a special meaning in
+URL encoding, so when issuing requests that place dates to the URL, take special care to ensure the data is properly URL
+encoded.
+
+## Design & new features
+
+If you intend to add a new feature, please allow the community to participate in the design process by creating an issue to discuss your design. For new features, the issue should describe what use cases the new feature intends to solve, or which existing use cases are being improved.
+
+Note Nighscout has a plugin architecture for adding new features. We expect most code for new features live inside a Plugin, so the code retains a clear separation of concerns. If the Plugin API doesn't implement all features you need to implement your feature, please discuss with us on adding those features to the API. Note new features should under almost no circumstances require changes to the existing plugins.
+
 ## Style Guide
 
 Some simple rules that will make it easier to maintain our codebase: