initial readme

README.md

+
+1. [Inventory Provider]
+   1. [Overview]
+   2. [Configuration]
+   3. [Running this module]
+   4. [Protocol specification]
+
+
+# Inventory Provider
+
+
+## Overview
+
+This module implements a Flask-based webservice which
+provides some access to GÉANT network router inventory
+information.
+
+The webservice is communicates with clients over HTTP.
+Responses to valid requests are returned as JSON messages.
+The server will therefore return an error unless
+`application/json` is in the `Accept` request header field.
+
+HTTP communication and JSON grammar details are
+beyond the scope of this document.
+Please refer to [RFC 2616](https://tools.ietf.org/html/rfc2616)
+and www.json.org for more details.
+
+
+## Configuration
+
+Several configuration files must be provided when launching
+the web service.
+
+The runtime-accessible filename of the first configuration file
+must be stored in the environment variable
+`SETTINGS_FILENAME`.
+
+The configuration file is python and defines a single variable.
+The following is an example:
+
+```python
+INVENTORY_PROVIDER_CONFIG_FILENAME = "/somepath/config.json"
+```
+
+- `INVENTORY_PROVIDER_CONFIG_FILENAME`: run-time accessible filename
+of a json file containing the server configuration parameters.  This file
+must be formatted according to the following json schema:
+
+    ```json
+    {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+            "alarms-db": {
+                "type": "object",
+                "properties": {
+                    "hostname": {"type": "string"},
+                    "dbname": {"type": "string"},
+                    "username": {"type": "string"},
+                    "password": {"type": "string"}
+                },
+                "required": ["hostname", "dbname", "username", "password"],
+                "additionalProperties": False
+            },
+            "oid_list.conf": {"type": "string"},
+            "routers_community.conf": {"type": "string"},
+            "ssh": {
+                "type": "object",
+                "properties": {
+                    "private-key": {"type": "string"},
+                    "known-hosts": {"type": "string"}
+                },
+                "required": ["private-key", "known-hosts"],
+                "additionalProperties": False
+            },
+            "redis": {
+                "type": "object",
+                "properties": {
+                    "hostname": {"type": "string"},
+                    "port": {"type": "integer"}
+                },
+                "required": ["hostname", "port"],
+                "additionalProperties": False
+            }
+        },
+        "required": [
+            "alarms-db",
+            "oid_list.conf",
+            "routers_community.conf",
+            "ssh",
+            "redis"],
+        "additionalProperties": False
+    }
+    ```
+
+
+## Running this module
+
+This module has been tested in the following execution environments:
+
+- As an embedded Flask application.
+For example, the application could be launched as follows:
+
+```bash
+$ export FLASK_APP=app.py
+$ export SETTINGS_FILENAME=settings.cfg
+$ flask run
+```
+
+- As an Apache/`mod_wsgi` service.
+  - Details of Apache and `mod_wsgi`
+configuration are beyond the scope of this document.
+
+
+## protocol specification
+
+The following resources can be requested from the webservice.
+
+### synchronous resources
+
+* `/data/version`
+
+  The response will be a JSON message formatted object
+  containing the module and protocol versions of the
+  running server and will be formatted as follows:
+
+  ```json
+  {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+            "api": {
+                "type": "string",
+                "pattern": r'\d+\.\d+'
+            },
+            "module": {
+                "type": "string",
+                "pattern": r'\d+\.\d+'
+            }
+        },
+        "required": ["api", "module"],
+        "additionalProperties": False
+    }
+  ```
+