Add standard request format

README.md

@@ -30,7 +30,62 @@ E.g. it works well to put all services on one machine except for the indices, wh
 servers for independent scaling. 
 We recommend putting each service behind an nginx proxy, which easily adds SSL support and improves performance. 
 
-# Docker 
+## Standard request format
+This is a standard format for request to and answers from an index (e.g. slide-index, wikipedia) or more
+general sources of related items. This way, new sources for related items can easily be added. 
+The service just needs to adhere to the standard request format and a few lines are added to
+the html5-client. 
+
+The micro service is queried via the POST endpoint: `/search`.
+The request contains the POST params `term` and `context`.
+
+The micro service returns a json object containing the response `type`
+and type-dependent data.
+
+For image:
+```
+{
+    "type": "image",
+    "paths": [
+        {
+            path: "/path/to/image/",
+            url: "/url/to/more/information/or/full/size/image"
+        },
+        {
+            path: "/path/to/image2/",
+            url: "/different/url/to/more/information/or/full/size/image2"
+        }
+    ]
+}
+```
+
+For texts:
+```
+{
+    "type": "text",
+    "texts": [
+        {
+            "text": "This will hopefully be useful information.",
+            "url": "http://example.com/"
+        },
+        {
+            "text": "This is about funny frog.",
+            "url": "/link/to/external/page"
+        }
+    ]
+}
+```
+
+If no information was found:
+```
+{
+    "type": "miss"
+}
+```
+
+An examples of an implementation with flask can be found in the slide-index repository.
+
+## Docker 
 There are docker containers available for the following components: 
 - [modified kaldi-model-server](https://hub.docker.com/repository/docker/fwelter/wilps-kaldi-model-server) 
 - [slide-index](https://hub.docker.com/repository/docker/fwelter/wilps_slide_index)
@@ -48,7 +103,7 @@ The message-broker is a trivial nodejs script and can easily be run on a bigblue
 If you have no experience with docker please check out [docker installation](https://docs.docker.com/get-started/)
 and [docker usage](https://docs.docker.com/get-started/part2/).
 
-# Nginx 
+## Nginx 
 This section gives an overview of the nginx setup and a general installation procedure. Please note
 that some steps may be redundant on your system and additional steps may be required (e.g. firewall exceptions)
 dependent on your setup. 
@@ -56,7 +111,7 @@ dependent on your setup.
 This setup also assumes that you have a registered (sub-)domain which points to your server(s),
 since this is required for SSL certificates.
 
-## Installation
+### Installation
 ```
 sudo apt update
 sudo apt install nginx
@@ -66,7 +121,7 @@ Make sure that the domain name is set up in the configuration e.g. `/etc/nginx/s
 The configuration needs to contain a line like `server_name example.com www.example.com`;
 Most likely the directive `server_name` is present and only the domain names need to be added.
 
-## SSL certificates
+### SSL certificates
 
 Install certbot and request SSL certificates. This automatically installs the SSL components for nginx.
 
@@ -79,7 +134,7 @@ sudo certbot --nginx -d example.com
 
 More details can be found here: https://www.digitalocean.com/community/tutorials/how-to-set-up-let-s-encrypt-with-nginx-server-blocks-on-ubuntu-16-04
 
-## Nginx reverse proxy
+### Nginx reverse proxy
 Nginx needs to know where your service is running. This can be done with the following
 example configuration: