Commit ebc7bfc5 authored by Siebers, Michael's avatar Siebers, Michael
Browse files

refined JSON schemas for /bg responses

parent e7775938
......@@ -19,21 +19,26 @@ Besides the usual JSON types (string, integer, number, object, array, boolean, a
we use the following type definitions in this documentation:
$ 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!
$ Path: A pseudo-absolute file system path (see [Path](<#json_path>)).
$ 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 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>)).
### Path {#json_path}
A _Path_ is a string specifying a file system 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!
A _Path_ follows [this JSON schema](<schema/type-path-schema.json>).
### File {#json_file}
A file is represented as a JSON object with the following properties:
......@@ -59,26 +64,6 @@ 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_manipulation}
The API response after a completed action is represented as a JSON object with the following properties:
| Property | Type | Example | Description |
| `Action` | nonnegative integer | =21= | The number of items to which `action` was successfully applied. |
| received | nonnegative integer | =42= | The number of items successfully parsed from the client's request. |
| skipped | nonnegative integer | =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
}
```
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.
......@@ -157,8 +142,19 @@ curl --request GET 'http://localhost:4444/bg/show'
| Case | Code | Description | Response Body |
| --- | --- | --- | --- |
| Created | `201` | Response if at least one element is successfully added | a _Manipulation Response_ with action `added` |
| No Change | `200` | Response if the item(s) are already present | a _Manipulation Response_ with action `added` |
| Created | `201` | Response if at least one element is successfully added | see below |
| No Change | `200` | Response if the item(s) are already present | see below |
In both cases, the response body is a JSON object with the following properties:
The API response after a completed action is a JSON object with the following properties:
| Property | Type | Example | Description |
| added | nonnegative integer | =21= | The number of items successfully added. |
| received | nonnegative integer | =42= | The number of items successfully parsed from the request body. |
| skipped | nonnegative integer | =0= | The number of items which could not be added (since they were already present). |
The result body is defined in this [JSON schema](<schema/response-bg-add-schema.json>), an example can be found below or in [the example file](<schema/response-bg-add-example.json>).
#### Example Call
......@@ -201,12 +197,16 @@ In contrast to `bg/clear`, remove allows for retracting the provided items only.
| Case | Code | Description | Response Body |
| --- | --- | --- | --- |
| Ok | `200` | Success | a _Manipulation Response_ with action `removed` |
| Ok | `200` | Success | see below |
#### Notes
The API response after a completed action is a JSON object with the following properties:
| Property | Type | Example | Description |
| removed | nonnegative integer | =21= | The number of items successfully removed. |
| received | nonnegative integer | =42= | The number of items successfully parsed from the request body. |
| skipped | nonnegative integer | =0= | The number of items which could not be removed (since they were not present). |
* See [JSON type definition](<#json_types>) for the request and reply json schemas.
* Will respond with `200` also if the item(s) were not present (i.e. skipped == received)
The result body is defined in this [JSON schema](<schema/response-bg-remove-schema.json>). , an example can be found below or in [the example file](<schema/response-bg-remove-example.json>).
#### Example Call
......
{
"$schema": "http://json-schema.org/draft-07/schema",
"$id": "type-manipulation-response-schema.json",
"$id": "type-bg-add-schema.json",
"title": "response /bg/add",
"description": "The reply body after adding items to the background knowledge",
"type": "object",
"title": "manipulation response",
"description": "The reply body after modifiying the background knowledge",
"properties": {
"received": {
"description": "The number of items received in the request body."
"type": "integer",
"minimum": 0
},
"skipped": {
"description": "The number of items not added because they were already present."
"type": "integer",
"minimum": 0
},
"added": {
"description": "The number of added items."
"type": "integer",
"minimum": 0
}
},
"required": [
"received",
"skipped"
"skipped",
"added"
],
"oneOf": [
{
"type": "object",
"properties": {
"added": {
"type": "integer",
"minimum": 0
}
},
"required": [
"added"
]
},
{
"type": "object",
"properties": {
"removed": {
"type": "integer",
"minimum": 0
}
},
"required": [
"removed"
]
}
]
"additionalProperties": false
}
......@@ -21,5 +21,6 @@
"remove_all",
"removed",
"skipped"
]
],
"additionalProperties": false
}
{
"received": 1,
"removed": 1,
"skipped": 0
}
{
"$schema": "http://json-schema.org/draft-07/schema",
"$id": "type-bg-remove-schema.json",
"title": "response /bg/remove",
"description": "The reply body after removing items from the background knowledge",
"type": "object",
"properties": {
"received": {
"description": "The number of items received in the request body."
"type": "integer",
"minimum": 0
},
"skipped": {
"description": "The number of items not removed because they were not present."
"type": "integer",
"minimum": 0
},
"removed": {
"description": "The number of items removed.",
"type": "integer",
"minimum": 0
}
},
"required": [
"received",
"skipped",
"removed"
],
"additionalProperties": false
}
......@@ -21,5 +21,6 @@
"required": [
"item_count",
"list"
]
],
"additionalProperties": false
}
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