In this document, we will describe the endpoints defined for the WebAPI. Endpoints are split in four categories:
In this document, we will describe the general input output systematics of the WebAPI and its defined endpoints for interaction.
1. [Background Knowledge Manipulation](<#bg>)
1. [Irrelevance](<#irrelecance>)
1. [Server Information](<#server>)
1. [Documentation](<#documentation>)
1. [JSON Types and Objects ](<#json_types>)
2. [Background Knowledge Manipulation](<#bg>)
3. [Irrelevance](<#irrelecance>)
4. [Server Information](<#server>)
5. [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.
The general input and output of the API is implemented with request/response methods that entail a body formatted as JSON. Therefore we will present custom JSON types and objects used throughout the endpoint descriptions first.
## JSON Types and Objects {#json_types}
Besides the usual JSON types (string, number, object, array, boolean, and null),
...
...
@@ -20,20 +21,21 @@ we use the following type definitions in this documentation:
$ 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
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 [Manipulation Response](<#json_response>)).
$ ManipulationResponse: A family of objects used as response in background manipulation (see [Manipulation Response](<#json_response>)).
### File {#json_file}
A JSON object with the following properties:
A file is represented as 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"|=. |
| type | string | yes | =|"file"|= | Denotes 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) |
...
...
@@ -42,15 +44,18 @@ A JSON object with the following properties:
| 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 |
[JSON Example for a valid file](<schema/filesystem-file-example.json>), accompanying schema definition [here](<schema/filesystem-data-schema.json>)
### Directory {#json_directory}
A JSON object with the following properties:
A directory is represented as 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) |
[JSON Example for a valid directory](<schema/filesystem-directory-example.json>), accompanying schema definition [here](<schema/filesystem-data-schema.json>)
### Manipulation Response {#json_response}
A JSON object with the following properties:
...
...
@@ -69,27 +74,27 @@ This type is rather a family of types, as `Action` is a variable property name.
"skipped": 0
}
```
The JSON schema for this type can be found in [background-response-schema.json](<schema/background-response-schema.json>).
For the accompanying schema definition see [here](<schema/background-response-schema.json>).
## Background Knowledge Manipulation {#bg}
There is 1 central stem `\bg` defined for manipulating the background knowledge with the following endpoints:
Background Knowledge Manipulation can be done via the following endpoints
* =|/bg/add|=
* =|/bg/show|=
* =|/bg/remove|=
* =|/bg/clear|=
| Endpoint | Description |
| --- | --- |
| ``/bg/show`` | Displays items currently present in the background knowledge |
| ``/bg/add`` | Adds items to background knowledge |
| ``/bg/remove`` | Removes certain items from the background knowledge |
