api_endpoints.md 18.3 KB
Newer Older
1
2
# API Endpoints

3
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/).
4

5
6
*Categories*:

7
    2. [Background Knowledge Manipulation](<#bg>)
8
    3. [Irrelevance](<#irrelevance>)
9
10
    4. [Server Information](<#server>)
    5. [Documentation](<#documentation>)
11
    
12
13
14
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>).
15
16
17


## JSON Types and Objects       {#json_types}
18
Besides the usual JSON types (string, integer, number, object, array, boolean, and null),
19
20
21
we use the following type definitions in this documentation:

    $ nonnegative integer: An integer greater than or equal to 0.
22
    $ Path: A pseudo-absolute file system path (see [Path](<#json_path>)).
23
24
    $ File: An object representing a file on disk (see [File](<#json_file>)).
    $ Directory: An object representing a directory on disk (see [Directory](<#json_directory>)).
25
26
    $ Item: An object representing either a file or a directory on disk.
    $ Error Response: The response body returned if the server encounters an error (see [Error Response](<#json_error>)).
27

28
29
30
31
32
33
34
35
36
37
38
39
40
41
### 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>).

    
42
### File       {#json_file} 
43
A file is represented as a JSON object with the following properties:
44
45

| Property | Type | Required | Example | Description |
46
| type | string | yes | =|"file"|= | Denotes that this object is a file. _Must_ have the value =|"file"|=. |
47
48
| 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 |
49
50
51
52
| creation_time | integer | yes | =|1391876828|= | the time the file was created as seconds since epoch (1970-01-01) |
| modification_time | integer | yes | =|1391876828|= | the time the file content was last modified as seconds since epoch (1970-01-01) |
| access_time | integer | yes | =|1391876828|= | the time the file was last accessed as seconds since epoch (1970-01-01) |
| change_time | integer | yes | =|1391876828|= | the time the file's metadata was last changed as seconds since epoch (1970-01-01) |
53
54
| media_type | string | yes | =|"img"|= | the media type of the file |

Siebers, Michael's avatar
Siebers, Michael committed
55
[JSON Example for a valid file](<schema/type-file-example.json>), accompanying schema definition [here](<schema/type-file-schema.json>).
56
57

### Directory      {#json_directory}
Sebastian Seufert's avatar
Sebastian Seufert committed
58
A directory is represented as a JSON object with the following properties:
59
60
61
62

| 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 |
63
| creation_time | integer | yes | =|1391876828|= | the time the file was created as seconds since epoch (1970-01-01) |
64

Siebers, Michael's avatar
Siebers, Michael committed
65
[JSON Example for a valid directory](<schema/type-directory-example.json>), accompanying schema definition [here](<schema/type-directory-schema.json>).
66

67
68
69
70
71
72
73
74
75
76
### 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>).
77
78

## Background Knowledge Manipulation        {#bg}
Sebastian Seufert's avatar
Sebastian Seufert committed
79
Background Knowledge Manipulation can be done via the endpoints ``/bg/show``, ``/bg/add``, ``/bg/remove`` and ``/bg/clear`` which are described below.
80

Sebastian Seufert's avatar
Sebastian Seufert committed
81
The handled background knowledge gets persisted per default, see [Persistency](Persistency) for details.
82

83
### Display current background knowledge {#get_bg}
84
85
86

| URL | Requires Auth | HTTP Method |
| --- | --- | --- |
87
| =|/bg/show|= | `no` | =GET= |
88
89

#### Parameters
Siebers, Michael's avatar
Siebers, Michael committed
90
None.
91

Sebastian Seufert's avatar
Sebastian Seufert committed
92
#### Return value
93
94
95

| Case | Code | Description | Response Body |
| --- | --- | --- | --- | 
96
| Ok | `200`| Request successful | a JSON object with properties `item_count` and `list` |
97

Siebers, Michael's avatar
Siebers, Michael committed
98
The property `item_count` (_nonnegative integer_) contains the number of items stored in the background knowledge. All items in the background knowledge are listed in `list` (list of [item](<#json_types>)s). The response body follows this [JSON schema](</doc/schema/response-bg-show-schema.json>).
99
100
101
102
103


#### Example Call

```
104
curl --request GET 'http://localhost:4444/bg/show'
105
106
```

Sebastian Seufert's avatar
Sebastian Seufert committed
107
#### Example Answer (200)
108
109
110
111

```
{
    "item_count": 1,
112
113
114
115
116
117
118
119
120
121
122
123
124
    "list": [
        {
            "abs_path": "testfile.ext",
            "access_time": 1604235569,
            "change_time": 1604235569,
            "creation_time": 1604235569,
            "file_size": 1024,
            "filename_extension": "ext",
            "media_type": "other",
            "modification_time": 1604235569,
            "type": "file"
        }
    ]
125
126
127
128
129
130
131
132
}
```


### Add items to background knowledge     {#add_bg}

| URL | Requires Auth | HTTP Method |
| --- | --- | --- |
133
| =|/bg/add|= | `no` | =POST= |
134
135
136

#### Parameters

137
138
| Argument | Example | Required | Description |
| --- | --- | --- | --- |
Siebers, Michael's avatar
Siebers, Michael committed
139
| _item_ or an array of _item_ | _see example call_ | Required | Asserts the arguments to the background knowledge.|
140

Sebastian Seufert's avatar
Sebastian Seufert committed
141
#### Return value
142
143
144

| Case | Code | Description | Response Body |
| --- | --- | --- | --- |
145
146
147
148
149
150
151
152
153
154
155
156
157
| 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>).
158
159
160
161

#### Example Call

```
Sebastian Seufert's avatar
Sebastian Seufert committed
162
curl --request POST 'http://localhost:4444/bg/add' 
163
164
165
--header 'Content-Type: application/json' 
--data-raw ' [   {
        "type" : "directory",
166
        "abs_path": "A/B",
167
168
169
170
        "creation_time": 1604235509
  }
 ]'
```
Sebastian Seufert's avatar
Sebastian Seufert committed
171
#### Example Answer (201)
172
173
174
175
176
177
178
179
180
181
182
183

```
{
    "received": 1,
    "added": 1,
    "skipped": 0
}
```


### Remove item from background knowledge     {#remove_bg}

Sebastian Seufert's avatar
Sebastian Seufert committed
184
185
In contrast to `bg/clear`, remove allows for retracting the provided items only.

186
187
| URL | Requires Auth | HTTP Method |
| --- | --- | --- |
Sebastian Seufert's avatar
Sebastian Seufert committed
188
| =|/bg/remove|= | `no` | =POST= |
189
190
191

#### Parameters

192
193
| Argument | Example | Required | Description |
| --- | --- | --- | --- | 
Siebers, Michael's avatar
Siebers, Michael committed
194
| _item_ or array of _item_ | _see example call_ | Required | Retracts the arguments from the background knowledge. |
195

Sebastian Seufert's avatar
Sebastian Seufert committed
196
#### Return value
197
198
199

| Case | Code | Description | Response Body |
| --- | --- | --- | --- |
200
| Ok | `200` | Success | see below |
201

202
203
204
205
206
207
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). |
208

209
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>).
210
211
212
213
214
215
216
217

#### Example Call

```bash
curl --request POST 'http://localhost:4444/clear' 
--header 'Content-Type: application/json' 
--data-raw ' [   {
        "type" : "directory",
218
        "abs_path": "A/B",
219
220
221
222
        "creation_time": 1604235509
  }
 ]'
```
Sebastian Seufert's avatar
Sebastian Seufert committed
223
#### Example Answer (200)
224
225
226
227
228
229
230
231
232
233
234
235

```bash
{
    "received": 1,
    "removed": 1,
    "skipped": 0
}
```


### Clear background knowledge      {#clear_bg}

Sebastian Seufert's avatar
Sebastian Seufert committed
236
In contrast to `bg/remove`, clear resets the background knowledge completely.
237

Sebastian Seufert's avatar
Sebastian Seufert committed
238
239
240
241
242
243
| URL | Requires Auth | HTTP Method |
| --- | --- | --- |
| =|/bg/clear|= | `no` | =POST= |

#### Parameters

244
None.
Sebastian Seufert's avatar
Sebastian Seufert committed
245
246
247
248
249
250


#### Return value

| Case | Code | Response Body |
| --- | --- | --- |
251
| Ok | `200` | a JSON object with properties `remove_all` (_boolean_), `removed` (_nonnegative integer_), and `skipped` (_nonnegative integer_)  |
Sebastian Seufert's avatar
Sebastian Seufert committed
252

253
254
255
    - `remove_all` is always `true` indicating that all items should have been removed
    - `removed` is the number of removed items
    - `skipped` is the number of ot removed items. Should always be zero.
Sebastian Seufert's avatar
Sebastian Seufert committed
256

Siebers, Michael's avatar
Siebers, Michael committed
257
258
The response body follows this [JSON schema](</doc/schema/response-bg-clear-schema.json>).
    
Sebastian Seufert's avatar
Sebastian Seufert committed
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
#### Example Call

```bash
curl --location --request POST 'http://localhost:4444/bg/clear'
```

#### Example Answer (200)

```bash
{
    "remove_all": true,
    "removed": 1,
    "skipped": 0
}
```
274
275

## Irrelevance      {#irrelevance}
276
The Reasoning WebAPI allows to query whether a single file is irrelevant and why this file is irrelvant.
277
278
279


### Query Irrelevance       {#query_irrelevance}
280
281
Queries whether a _single file_ is irrelevant.

282
283
| URL | Requires Auth | HTTP Method |
| --- | --- | --- |
284
| =|/irrelevant/file|= | `no` | `POST` |
285
286
287
288
289

#### Parameters

| Argument | Example | Type | Required | Description |
| --- | --- | --- | --- | --- |
290
| =abs_path= | see example call | _Path_ | Required | =abs_path= serves as UID of the item in question |
291

Sebastian Seufert's avatar
Sebastian Seufert committed
292
#### Return value
293
294
295

| Case | Code | Description | Response Body |
| --- | --- | --- | --- |
296
| Ok | `200` | Success | JSON object with property `result` (=boolean=) |
297

298
The response body follows this [JSON schema](</doc/schema/response-irrelevant-file-schema.json>).
299
300
301
302
303
304
305
306

#### Example Call

```bash
curl --request POST 'http://localhost:4444/irrelevant/file' \
--header 'Content-Type: application/json' \
--data-raw '
{
307
    "abs_path": "A/file1.ext"
308
309
310
}
'
```
Sebastian Seufert's avatar
Sebastian Seufert committed
311
#### Example Answer (200)
312
313
314

```bash
{
315
    "result": true
316
317
318
319
320
}
```


### Explain Irrelevance {#explain_irrelevance}
321
322
Explains why an irrelevant file is irrelevant.

323
324
325
326
327
328
329
330
| URL | Requires Auth | HTTP Method |
| --- | --- | --- |
| =|/explain|= | `no` | =POST= |

#### Parameters

| Argument | Example | Type | Required | Description |
| --- | --- | --- | --- | --- |
331
332
| =abs_path= | "A/file1.ext" | =Path= | yes | the path of the irrelevant file that an explanation is requested for |
| =limit= | 3 | =|nonnegative integer|= | no (default 5) | the maximal number of explanations to return | 
333

Sebastian Seufert's avatar
Sebastian Seufert committed
334
#### Return value
335
336
337

| Case | Code | Description | Response Body |
| --- | --- | --- | --- | 
338
339
340
341
342
343
344
345
| Ok | `200` | explanation(s) successfully created | JSON object with properties `explanations` and `further_explanations` (=boolean=) | 
| Bad Request | `400` | item is not irrelevant and thus requesting an explanation is not possible | JSON object with properties `code` and `message` |

    - `explanations`: A list of explanations (see below).
    - `further_explanations`: `true` if more explanations are available
    - `code`: the HTTP status code (400)
    - `message`: an error message

Siebers, Michael's avatar
Siebers, Michael committed
346
On success, the response body follows this [JSON schema](</doc/schema/response-explain-schema.json>). Otherwise, the response body follows the [error schema](</doc/schema/response-error-schema.json>).
347
348


Siebers, Michael's avatar
Siebers, Michael committed
349
350
351
352
353
354
355
#### Explanations
An explanation consists of four parts:
    - the path of the irrelevant file explained (`abs_path`, Path),
    - a top-level view reasoning why the file is irrelevant (`reasoning`),
    - a detailed step-by-step reasoning why the file is irrelevant (`reasoning_details`), and
    - references to the 'real-world' file system (`references`).
 
356
357
358
359
360
361
362

#### Example Call

```bash
curl --request POST 'http://localhost:4444/explain' \
--header 'Content-Type: application/json' \
--data-raw '{
363
    "abs_path": "A/file1.ext",
364
365
366
367
    "limit": 1
}'
```

368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
#### Example Answer (200)
```
{
    "explanations": [
        {
            "abs_path": "A/file1.ext",
            "reasoning": [
                { "text": "" }
            ],
            "reasoning_details": [
                [
                    { "text": "die Dateien " },
                    { "ref_id": 0, "text": "file1.ext" },
                    { "text": " und " },
                    { "ref_id": 1, "text": "file2.ext"},
                    { "text": " sind im gleichen Verzeichnis." }
                ],
                [
                    { "text": "Datei "},
                    { "ref_id": 1, "text": "file2.ext" },
                    { "text": " ist " },
                    { "ref_id": 2, "text": "neuer" },
                    { "text": " als Datei " },
                    { "ref_id": 0, "text": "file1.ext" },
                    { "text": "." }
                ]
            ],
            "references": [
                {
                    "id": 2,
                    "referenced_entities": [
                        {
                            "abs_path": "A/file2.ext",
                            "property": "mtime"
                        },
                        {
                            "abs_path": "A/file1.ext",
                            "property": "mtime"
                        }
                    ]
                },
                {
                    "id": 1,
                    "referenced_entities": [
                        {
                            "abs_path": "A/file2.ext",
                            "property": "name"
                        }
                    ]
                },
                {
                    "id": 0,
                    "referenced_entities": [
                        {
                            "abs_path": "A/file1.ext",
                            "property": "name"
                        }
                    ]
                }
            ]
        }
    ],
    "further_explanations": false
}
```

434
## Server Information        {#server}
435
To receive basic information on the currently running server you may query the server status.
436
437
438
439
440
441
442
443
444
445

### Query Server Status     {#server_status}
| URL | Requires Auth | HTTP Method |
| --- | --- | --- |
| =|/state|= | `no` | =GET= |

#### Parameters

None.

Sebastian Seufert's avatar
Sebastian Seufert committed
446
#### Return value
447

Sebastian Seufert's avatar
Sebastian Seufert committed
448
This endpoint always Return value _200 OK_ along with a JSON object describing the 
449
450
451
452
453
status of the server.

| Property | Type | Description |
|   ---     |   --- |   ---     |
| =status= | string | The status of the server. Currently, always =|"running"|=. |
Siebers, Michael's avatar
Siebers, Michael committed
454
| =version= | string | The [semantic version number](https://semver.org) of the WebAPI. |
455

Siebers, Michael's avatar
Siebers, Michael committed
456
The response body follows this [JSON schema](</doc/schema/response-state-schema.json>).
457
458
459
460
461
462
463
464


#### Example Call

```bash
curl --request GET 'http://localhost:4444/state'
```

Siebers, Michael's avatar
Siebers, Michael committed
465
466
467
468
469
470
471
#### Example Answer (200)
```
{
    "status": "running",
    "version": "1.0.0"
}
```
472

473
## Limitations          {#limitations}
474
475
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.

476
477
478
479
480
481
482
483
### 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. 

However, this limitation only affects the body as a whole. For instance, the body =|{"key": 1,2,3]}|= results in a parsing error since JSON properties must be strings (and `2` is not).

### JSON Arrays
Unlike the JSON standard, the JSON parser ignores a trailing comma in arrays.

484
485
486
487
488
### 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)

489
490
491
492
493
494
495
496
497
## 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 |