copied and reformatted API endpoints from WIKI

moved schemas

close #31

doc/api_endpoints.md

+# API Endpoints
+
+In this document, we will describe the endpoints defined for the WebAPI. Endpoints are split in four categories:
+
+    1. [Background Knowledge Manipulation](<#bg>)
+    1. [Irrelevance](<#irrelecance>)
+    1. [Server Information](<#server>)
+    1. [Documentation](<#documentation>)
+    
+Each category will be detailed in its own section below. For each endpoint detailed in the sections, we will give the expected HTTP request method, handled parameters, the expected body, possible HTTP return codes, the response body on success, and give an example call using the [curl command line tool](https://curl.se/).
+
+Before describing the endpoints and their categories, we will present custom JSON types used throughout the endpoint descriptions.
+
+## JSON Types and Objects       {#json_types}
+Besides the usual JSON types (string, number, object, array, boolean, and null),
+we use the following type definitions in this documentation:
+
+    $ integer: An integer number.
+    $ nonnegative integer: An integer greater than or equal to 0.
+    $ Path: A string specifying a path. Path delimiter is the slash =|"/"|=. 
+            A Path is interpreted as pseudo-absolute path. That means that every
+            path is considered absolute and not interpreted relative to some 
+            other path. For example the path =|"A/B"|= is interpreted as =B= in 
+            directory =A=, where =A= itself is in no other directory. Thus, =A= 
+            is assumed to be _|a|_(!) root directory. The empty string (=|""|=) 
+            is not a valid Path. The *nix root is represented by a single slash
+            (=|"/"|=). No other Path may end in a slash! 
+    $ File: An object representing a file on disk (see [File](<#json_file>)).
+    $ Directory: An object representing a directory on disk (see [Directory](<#json_directory>)).
+    $ ManipulationResponse: A family of objects used as response in background manipulation (see [ManipulationResponse](<#json_response>)).
+
+### File       {#json_file} 
+A JSON object with the following properties:
+
+| Property | Type | Required | Example | Description |
+| type | string | yes | =|"file"|= | Informs that this object is a file. _Must_ have the value =|"file"|=. |
+| abs_path | Path | yes | =|"A/B/Filename.ext"|= | the absolute path of the file |
+| file_size | nonnegative integer | yes | =|143547|= | the size of the file in bytes |
+| creation_time | integer | yes | =|1391876828|= | the time the file was created as seconds since epoch (1970-07-07) |
+| modification_time | integer | yes | =|1391876828|= | the time the file content was last modified as seconds since epoch (1970-07-07) |
+| access_time | integer | yes | =|1391876828|= | the time the file was last accessed as seconds since epoch (1970-07-07) |
+| change_time | integer | yes | =|1391876828|= | the time the file's metadata was last changed as seconds since epoch (1970-07-07) |
+| media_type | string | yes | =|"img"|= | the media type of the file |
+
+
+### Directory      {#json_directory}
+A JSON object with the following properties:
+
+| Property | Type | Required | Example | Description |
+| type | string | yes | =|"directory"|= | Informs that this object is a file. _Must_ have the value =|"directory"|=. |
+| abs_path | Path | yes | =|"A/B"|= | the absolute path of the file |
+| creation_time | integer | yes | =|1391876828|= | the time the file was created as seconds since epoch (1970-07-07) |
+
+### ManipulationResponse      {#json_response}
+A JSON object with the following properties:
+
+| Property | Type | Required | Example | Description |
+| `Action` | nonnegative integer | yes | =21= | The number of items which were successfully processed. |
+| received | nonnegative integer | yes | =42= | The number of items successfully parsed from the client's request. |
+| skipped | nonnegative integer | yes | =0= | The number of items which were not processed. |
+
+This type is rather a family of types, as `Action` is a variable property name. The used property depends on the action taken. An instance of this type (for `Action` =removed=) may look as follows.
+
+
+```
+{
+    "received": 1,
+    "removed": 1,
+    "skipped": 0
+}
+```
+
+The JSON schema for this type can be found in [background-response-schema.json](<schema/background-response-schema.json>).
+
+
+## Background Knowledge Manipulation        {#bg}
+There are 2 endpoints defined for background knowledge:
+
+    * =|/bg|=
+    * =|/clear|=
+
+    
+The background knowledge gets persisted per default, see [Persistency](Persistency) for details.
+
+
+### Retrieve items in background knowledge {#get_bg}
+
+| URL | Requires Auth | HTTP Method |
+| --- | --- | --- |
+| =|/bg|= | `no` | =GET= |
+
+#### Parameters
+(none)
+
+#### Returns
+
+| Case | Code | Description | Response Body |
+| --- | --- | --- | --- | 
+| Ok | `200`| a JSON object with property `item_count` and a detailed list <PARAMETER NAME> | see example answer |
+
+The list <PARAMETER NAME> is a list of [filesystem items](<#items>).
+
+
+#### Example Call
+
+```
+curl --request GET 'http://localhost:4444/bg'
+```
+
+#### Example Answer Body (200)
+
+```
+{
+    "item_count": 1,
+    "list": [{
+            "abs_path": "/A/B",
+            "creation_time": 1604235509
+        }]
+}
+```
+
+
+### Add items to background knowledge     {#add_bg}
+
+| URL | Requires Auth | HTTP Method |
+| --- | --- | --- |
+| =|/bg|= | `no` | =POST= |
+
+#### Parameters
+
+| Argument | Example | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| item or list of items | see example call | POST body | Required | Asserts the list into the background knowledge.|
+
+
+#### Returns
+
+| Case | Code | Description | Response Body |
+| --- | --- | --- | --- |
+| Created | `201` | Responded if at least one element is successfully added | see example answer |
+| No Change | `200` | Responded if the item(s) are already present| 
+
+#### Example Call
+
+```
+curl --request POST 'http://localhost:4444/bg' 
+--header 'Content-Type: application/json' 
+--data-raw ' [   {
+        "type" : "directory",
+        "abs_path": "/A/B",
+        "creation_time": 1604235509
+  }
+ ]'
+```
+#### Example Answer Body (201)
+
+```
+{
+    "received": 1,
+    "added": 1,
+    "skipped": 0
+}
+```
+
+
+### Remove item from background knowledge     {#remove_bg}
+
+| URL | Requires Auth | HTTP Method |
+| --- | --- | --- |
+| =|/clear|= | `no` | =POST= |
+
+#### Parameters
+
+| Argument | Example | Type | Required | Description |
+| --- | --- | --- | --- | --- | 
+| =list of item(s)= | see example call | POST body | Required | Clears the received items from the background knowledge. |
+
+#### Returns
+
+| Case | Code | Description | Response Body |
+| --- | --- | --- | --- |
+| Ok | `200` |  | see example answer |
+
+#### Notes
+
+    * See [here](<schema/filesystem-data-schema.json>) for the detailled json schema.
+    * Will respond with `200` also if the item(s) were not present (i.e. skipped == received)
+
+#### Example Call
+
+```bash
+curl --request POST 'http://localhost:4444/clear' 
+--header 'Content-Type: application/json' 
+--data-raw ' [   {
+        "type" : "directory",
+        "abs_path": "/A/B",
+        "creation_time": 1604235509
+  }
+ ]'
+```
+#### Example Answer Body (200)
+
+```bash
+{
+    "received": 1,
+    "removed": 1,
+    "skipped": 0
+}
+```
+
+
+### Clear background knowledge      {#clear_bg}
+
+
+
+## Irrelevance      {#irrelevance}
+
+    * =|/irrelevant|=
+    * =|/explain|=
+
+---
+
+Todo:
+
+    * Error Messages
+    * Link examples
+
+----
+
+### Query Irrelevance       {#query_irrelevance}
+| URL | Requires Auth | HTTP Method |
+| --- | --- | --- |
+| `/irrelevant` | `no` | `POST` |
+
+#### Parameters
+
+| Argument | Example | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| =|"abs_path": "<ID>"|= | see example call | POST body | Required | =abs_path= serves as UID of the item in question |
+
+#### Returns
+
+| Case | Code | Description | Response Body |
+| --- | --- | --- | --- |
+| Ok | `200` | | see example below |
+
+#### Notes
+* (ToDo: Link to Schema-explanation)
+
+#### Example Call
+
+```bash
+curl --request POST 'http://localhost:4444/irrelevant/file' \
+--header 'Content-Type: application/json' \
+--data-raw '
+{
+    "abs_path": "/A/B/Filename.exe"
+}
+'
+```
+#### Example Answer Body (200)
+
+```bash
+{
+    "result": false
+}
+```
+
+
+### Explain Irrelevance {#explain_irrelevance}
+| URL | Requires Auth | HTTP Method |
+| --- | --- | --- |
+| =|/explain|= | `no` | =POST= |
+
+#### Parameters
+
+| Argument | Example | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| =|"abs_path": "<ID>"|= & =|"limit": "<INT>"|= | see example call | POST body | Required | 
+
+#### Returns
+
+| Case | Code | Description | Response Body |
+| --- | --- | --- | --- | 
+| Ok | `200` | `abs_path` serves as UID of the item in question, `limit` is the limit of possible explanations that shall be returned if more than one explanation can be generated | 
+| Bad Request | `400` | item is not irrelevant & thus requesting an explanation is not possible | |
+
+#### Notes
+    * The status code in the second case is under [discussion](https://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/20) and might be changed with refined error handling / messaging
+
+#### Example Call
+
+```bash
+curl --request POST 'http://localhost:4444/explain' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "abs_path": "/A/B/Filename.exe",
+    "limit": 1
+}'
+```
+
+## Server Information        {#server}
+To receive basic information on the currently running server you may query the
+server status.
+
+### Query Server Status     {#server_status}
+| URL | Requires Auth | HTTP Method |
+| --- | --- | --- |
+| =|/state|= | `no` | =GET= |
+
+#### Parameters
+
+None.
+
+#### Returns
+
+This endpoint always returns _200 OK_ along with a JSON object describing the 
+status of the server.
+
+| Property | Type | Description |
+|   ---     |   --- |   ---     |
+| =status= | string | The status of the server. Currently, always =|"running"|=. |
+| =version= | string | The version number of the WebAPI server. |
+
+
+
+#### Example Call
+
+```bash
+curl --request GET 'http://localhost:4444/state'
+```
+
+
+## Documentation        {#documentation}
+
+When started with the =|--documentation|= switch, the WebAPI server serves its own documentation as HTML pages. The documentation can be accessed using =GET= requests, for example using a conventional web browser.
+
+| URL | Requires Auth | Content |
+| --- | --- | --- |
+| =|/doc/|= | `no` | Main documentation, guides, this page, ... |
+| =|/doc/pldoc/|= | `no` | Prolog predicate comments, see [SWI-Prolog Source Documentation](<pldoc/doc_for?object=section('packages/pldoc.html')>) |
+| =|/doc/schema/|= | `no` | JSON schema definitions |