Commit 67fa897c authored by Siebers, Michael's avatar Siebers, Michael
Browse files

document JSON error scheme and exceptions

Closes #62
parent ae582a10
......@@ -2,20 +2,22 @@
In this document, we will describe the general input output systematics of the WebAPI and its defined endpoints for interaction. 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/).
1. [JSON Types and Objects ](<#json_types>)
*Categories*:
2. [Background Knowledge Manipulation](<#bg>)
3. [Irrelevance](<#irrelevance>)
4. [Server Information](<#server>)
5. [Documentation](<#documentation>)
In general, the request bodies (if required) and responses are formatted as JSON documents.
Thus, we will present custom JSON types and objects used throughout the endpoint descriptions first.
For limitations on JSON parsing and generation see section [Limitations](<#limitations>).
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),
Besides the usual JSON types (string, integer, 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
......@@ -28,8 +30,9 @@ we use the following type definitions in this documentation:
(=|"/"|=). 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>)).
$ Item: An object representing a file or a directory on disk.
$ Manipulation Response: A family of objects used as response in background manipulation (see [Manipulation Response](<#json_response>)).
$ Item: An object representing either a file or a directory on disk.
$ Manipulation Response: A family of objects used as response in background manipulation (see [Manipulation Response](<#json_manipulation>)).
$ Error Response: The response body returned if the server encounters an error (see [Error Response](<#json_error>)).
### File {#json_file}
A file is represented as a JSON object with the following properties:
......@@ -56,7 +59,7 @@ A directory is represented as a JSON object with the following properties:
[JSON Example for a valid directory](<schema/type-directory-example.json>), accompanying schema definition [here](<schema/type-directory-schema.json>).
### Manipulation Response {#json_response}
### Manipulation Response {#json_manipulation}
The API response after a completed action is represented as a JSON object with the following properties:
| Property | Type | Example | Description |
......@@ -76,6 +79,16 @@ This type is rather a family of types, as `Action` is a variable property name.
```
For the accompanying schema definition see [here](<schema/type-manipulation-response-schema.json>).
### Error Response {#json_error}
When a request does not succeed or the server encounters an error it returns with a status code outside the 200 range. This usually signals an error (in the 400 or 500 range). If the requested endpoint is not serving the documentation (see section [Documentation](<#documentation>)), the response body consists of a JSON object detailing the error.
| Property | Type | Required | Example | Description |
| code | nonnegative integer | yes | =|400|= | The status code this error caused. _Must_ be the same as the returned status code. |
| location | string | no | =|"/doc/index.html"|= | The location this error refers to. |
| message | string | yes | =|"Unexpected end of request body"|= | A detailed message what caused the error. |
| method | string | no | =|"OPTIONS"|= | The HTTP method of the offending endpoint. |
[JSON Example for an error response](<schema/response-error-example.json>), accompanying schema definition [here](<schema/response-error-schema.json>).
## Background Knowledge Manipulation {#bg}
Background Knowledge Manipulation can be done via the endpoints ``/bg/show``, ``/bg/add``, ``/bg/remove`` and ``/bg/clear`` which are described below.
......@@ -453,6 +466,8 @@ curl --request GET 'http://localhost:4444/state'
```
## Limitations {#limitations}
Due to technical difficulties, neither is perfect. The library-standard HTTP server and the included JSON parsing mechanism are not perfect. Thus, some limitations on parsing JSON requests and generating JSON responses are imposed.
### Request Bodies with JSON
The current implementation restricts the JSON content of request bodies. Only the first JSON _entity_ is parsed, the remaining text in the body is *silently* discarded. The parsed entity may be of any basic JSON type, like a string, an object, or an array. This may lead to unexpected results on erroneous input. For example, the incomplete array =|1,2,3]|= would be parsed as the integer `1` while the remainig characters are ignored without warning.
......@@ -461,6 +476,11 @@ However, this limitation only affects the body as a whole. For instance, the bod
### JSON Arrays
Unlike the JSON standard, the JSON parser ignores a trailing comma in arrays.
### JSON Error Bodies
The values of some HTTP headers are inspected by the HTTP server before beeing handed over to the WebAPI module. If the value for the header field is not permissible, the HTTP server responds with a `400 Bad Request` response. However, the body of the response will not be an JSON document but an HTML document.
> For a technical discussion of the underlying problem see [issue #62](https://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/62)
## 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.
......
{
"code": 405,
"location": "/bg/show",
"message": "Method not allowed: PUT",
"method": "PUT"
}
Supports Markdown
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