Commit 1dd752e6 authored by Sebastian Seufert's avatar Sebastian Seufert
Browse files

- modified css to show heading numbering

- changes to api_endpoints.md
parent d9349041
# API Endpoints
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>)).
$ Manipulation Response: 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 |
| ``/bg/clear`` | Clears background knowledge completely |
The background knowledge gets persisted per default, see [Persistency](Persistency) for details.
### Retrieve items in background knowledge {#get_bg}
### Displays current Background Knowledge {#get_bg}
| URL | Requires Auth | HTTP Method |
| --- | --- | --- |
| =|/bg|= | `no` | =GET= |
| =|/bg/show|= | `no` | =GET= |
#### Parameters
(none)
......@@ -100,13 +105,13 @@ The background knowledge gets persisted per default, see [Persistency](Persisten
| --- | --- | --- | --- |
| 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>).
The list <PARAMETER NAME> is a list of [filesystem items](<#json_types>) that are currently present in the background knowledge.
#### Example Call
```
curl --request GET 'http://localhost:4444/bg'
curl --request GET 'http://localhost:4444/bg/show'
```
#### Example Answer Body (200)
......@@ -126,7 +131,7 @@ curl --request GET 'http://localhost:4444/bg'
| URL | Requires Auth | HTTP Method |
| --- | --- | --- |
| =|/bg|= | `no` | =POST= |
| =|/bg/add|= | `no` | =POST= |
#### Parameters
......
......@@ -157,3 +157,29 @@ div.wiki_wrapper table.wiki tr:nth-child(even){background-color: #f8f8f8;}
float: right;
}
h1 { counter-reset: h2counter; }
h2 { counter-reset: h3counter; }
h3 { counter-reset: h4counter; }
h4 { counter-reset: h5counter; }
h5 { counter-reset: h6counter; }
h2:before {
counter-increment: h2counter;
content: counter(h2counter) ".\0000a0\0000a0";
}
h3:before {
counter-increment: h3counter;
content: counter(h2counter) "." counter(h3counter) ".\0000a0\0000a0";
}
h4:before {
counter-increment: h4counter;
content: counter(h2counter) "." counter(h3counter) "." counter(h4counter) ".\0000a0\0000a0";
}
h5:before {
counter-increment: h5counter;
content: counter(h2counter) "." counter(h3counter) "." counter(h4counter) "." counter(h5counter) ".\0000a0\0000a0";
}
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment