a few updates to protocol specs

README.md

 
-1. [Inventory Provider]
-   1. [Overview]
-   2. [Configuration]
-   3. [Running this module]
-   4. [Protocol specification]
-   5. [backend (Redis) storage schema]
+* [Inventory Provider](#inventory-provider)
+  * [Overview](#overview)
+  * [Configuration](#configuration)
+  * [Running this module](#running-this-module)
+  * [Protocol Specification](#protocol-specification)
+  * [Backend (Redis) Storage Schema](#backend-redis-storage-schema)
 
 
 
@@ -157,10 +157,14 @@ $ flask run
 
 - As an Apache/`mod_wsgi` service.
   - Details of Apache and `mod_wsgi`
-configuration are beyond the scope of this document.
+    configuration are beyond the scope of this document.
 
+- As a `gunicorn` wsgi service.
+  - Details of `gunicorn` configuration are
+    beyond the scope of this document.
 
-## protocol specification
+
+## Protocol Specification
 
 The following resources can be requested from the webservice.
 
@@ -299,32 +303,51 @@ Any non-empty responses are JSON formatted messages.
 * /jobs/update
 
   This resource updates the inventory network data for juniper devices.
+  The function completes asynchronously and a list of outstanding
+  task id's is returned so the caller can
+  use `/jobs/check-task-status` to determine when all jobs
+  are finished.  The response will be formatted as follows:
 
-* /jobs/update-startup
+  ```json
+  {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "array",
+    "items": {"type": "string"}
+  }
+  ```
 
-  This resource updates data that should only be refreshed
-  in case of system restart.
-  
-* /jobs/update-interfaces-to-services
+* /jobs/reload-router-config/<equipment-name>
 
-  This resource updates the information that lists all the services for
-  interfaces found in the external inventory system
-  
-* /jobs/update-service-hierarchy
+  This resource updates the inventory network data for
+  the identified juniper device.  This function completes
+  asynchronously and returns the same value as
+  `/jobs/update`, except the return contains exactly
+  one task id.
 
-  This resource updates all the information showing which services are related
-  to one-another
-  
-* /jobs/update-equipment-locations
+* /jobs/check-task-status/<task-id>"
+
+  This resource returns the current status of
+   an asynchronous task started by `/jobs/update`
+   or `jobs/reload-router-config`.  The return value
+   will be formatted as follows:
+
+  ```json
+  {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "properties": {
+        "id": {"type": "string"},
+        "status": {"type": "string"},
+        "exception": {"type": "boolean"},
+        "ready": {"type": "boolean"},
+        "success": {"type": "boolean"},
+        "result": {"type": "object"}
+    },
+    "required": ["id", "status", "exception", "ready", "success"],
+    "additionalProperties": False
+  }
+  ```
 
-  This resource loads the location information for all the equipment from the
-  external inventory system
-  
-* /jobs/update-from-inventory-system
-  
-  This resource updates the inventory data from the external inventory system,
-  it is a short cut for executing the above three jobs
-  
 * /jobs/update-interface-statuses
 
   This resource updates the last known statuses of all interfaces extracted
@@ -402,15 +425,25 @@ Any non-empty responses are JSON formatted messages.
     }
     ```
 
-## backend (Redis) storage schema
 
-`netconf:<hostname>`
+* `/testing/flushdb`
+
+  This method erases all data in the backend redis
+  data bases and is only available if the server was
+  started with the `ENABLE_TESTING_ROUTES` flag.
+
+
+## Backend (Redis) Storage Schema
+
+* `netconf:<hostname>`
+
   * key example
     * `netconf:mx1.ams.nl.geant.net`
   * value format
     * cf. validation in `inventory_provider.juniper.load_config`
 
-`snmp-interfaces:<hostname>`
+* `snmp-interfaces:<hostname>`
+
   * key example:
     * `snmp-interfaces:mx1.lon2.uk.geant.net`
   * value schema
@@ -475,7 +508,7 @@ Any non-empty responses are JSON formatted messages.
     ```
 
 
-`opsdb:interface_services:<equipment name>:<interface name>`
+* `opsdb:interface_services:<equipment name>:<interface name>`
 
   * key examples
     * `opsdb:interface_services:mx1.ams.nl.geant.net:ae15.1103`
@@ -550,7 +583,7 @@ Any non-empty responses are JSON formatted messages.
     ```
 
 
-`opsdb:location:<equipment name>`
+* `opsdb:location:<equipment name>`
 
   * key examples
     * `opsdb:location:mx1.ams.nl.geant.net`
@@ -581,8 +614,8 @@ Any non-empty responses are JSON formatted messages.
     }
     ```
 
-`opsdb:services:children:<circuit db id>`
-`opsdb:services:parents:<circuit db id>`
+* `opsdb:services:children:<circuit db id>`
+* `opsdb:services:parents:<circuit db id>`
 
   * key examples
     * `opsdb:services:children:12363`
@@ -634,7 +667,7 @@ Any non-empty responses are JSON formatted messages.
     }
     ```
 
-`alarmsdb:interface_status:<equipment name>:<interface name>`
+* `alarmsdb:interface_status:<equipment name>:<interface name>`
   * key examples
     * `alarmsdb:interface_status:Lab node 1:1-1/3`
     *  `alarmsdb:interface_status:mx1.ams.nl.geant.net:ae15.1500`
@@ -645,7 +678,7 @@ Any non-empty responses are JSON formatted messages.
     * `down`
 
 
-`ix_public_peer:<address>`
+* `ix_public_peer:<address>`
   * key examples
     * `ix_public_peer:193.203.0.203`
     * `ix_public_peer:2001:07f8:00a0:0000:0000:5926:0000:0002`
@@ -683,7 +716,37 @@ Any non-empty responses are JSON formatted messages.
     }
     ```
 
-`vpn_rr_peers/<address>`
+* `vpn_rr_peers/<address>`
+  * key examples
+    * `ix_public_peer:193.203.0.203`
+  * valid values:
+    ```json
+    {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+
+        "definitions": {
+            "ip-address": {
+                "type": "string",
+                "oneOf": [
+                    {"pattern": r'^(\d+\.){3}\d+$'},
+                    {"pattern": r'^([a-f\d]{4}:){7}[a-f\d]{4}$'}
+                ]
+            }
+        },
+
+        "type": "object",
+        "properties": {
+            "name": {"$ref": "#/definitions/ip-address"},
+            "description": {"type": "string"},
+            "peer-as": {"type": "integer"}
+        },
+        "required": ["name", "description"],
+        "additionalProperties": False
+    }
+    ```
+
+
+* `vpn_rr_peers/<address>`
   * key examples
     * `ix_public_peer:193.203.0.203`
   * valid values: