Added API documentation.

README.md

@@ -44,3 +44,101 @@ After this your project structure should look like this:
     ├── artisan
     ├── ...
 ```
+
+## API
+
+### `(GET) /next`
+Returns the next unused experiment input.
+Additional experiment input can be uploaded as CVS on the `Experiments` page.
+
+Example responses:
+
+```json
+{
+  "code": 1,
+  "message": "No more experiment data available",
+  "data": null
+}
+```
+
+```json
+{
+  "code": 0,
+  "message": "OK",
+  "data": {
+    "condition": 1
+  },
+  "id": "l3kRmh6Bp6nsmnDvi9PJzk6rubyTOck9vSMX5xqnewKkgGOfn8HjWEWNWfP6"
+}
+```
+
+``id`` is the a unique ID for this experiment run and can be used to
+reference the input data (and marking the experiment as complete) when
+submitting the data (see below).
+
+**Note**: Right now the server automatically marks the input data as being
+used for a running experiment and will not use it for a second time
+(even if no results have been submitted).
+(*Which might be a good reason to make this route a POST route, since
+it changes state in the database!*)
+
+### `(POST) /submit`
+Can be used to submit experiment results to the server.
+Data can be marked as partial or as belonging to a given experiment input.
+Only the ``data`` field is required and can be of any type (except ``null``).
+
+Example requests:
+
+```json
+{
+  "data": {
+    "my-example-field1": 2,
+    "my-example-field2": "some string"
+    }
+}
+```
+
+```json
+{
+  "data": [1, 2, 3, 4, 5],
+  "partial": true,
+  "id": "l3kRmh6Bp6nsmnDvi9PJzk6rubyTOck9vSMX5xqnewKkgGOfn8HjWEWNWfP6"
+}
+```
+
+Example responses:
+
+```json
+{
+  "code": 0,
+  "message": "Result submitted.",
+  "session": "l3kRmh6Bp6nsmnDvi9PJzk6rubyTOck9vSMX5xqnewKkgGOfn8HjWEWNWfP6"
+}
+```
+
+**Note**: The ``session`` should be named ``id`` and will probably be
+renamed in the future.
+It is present, even if no `id` was submitted and can be used in future
+submission to mark the result data as belonging to the same experiment.
+(Useful, if partial data is submitted.)
+
+```json
+{
+  "code": 3,
+  "message": "Invalid data format. Please provide valid JSON.",
+}
+```
+
+Returned if the ``data`` field is missing or ``null``.
+
+```json
+{
+  "code": 500,
+  "message": "Your request caused a server error. It has been logged."
+}
+```
+
+Returned if the request caused a server error.
+This could happen, if the submitted data is too large and the
+server runs out of memory.
+The error details will be saved in the server logs.