Demonstrator - Reasoning WebAPI issueshttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues2021-06-12T09:00:31Zhttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/51document JSON schemas2021-06-12T09:00:31ZSiebers, Michaeldocument JSON schemas- revise JSON schemas below `doc/schema`
- link JSON schemas in [api_endpoints.md](doc/api_endpoints.md) where appropriate
- write [schema overview](doc/schema/index.html)- revise JSON schemas below `doc/schema`
- link JSON schemas in [api_endpoints.md](doc/api_endpoints.md) where appropriate
- write [schema overview](doc/schema/index.html)Version 1.0https://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/52revise API endpoint documentation2021-06-12T09:00:31ZSiebers, Michaelrevise API endpoint documentationreview and amend [api_endpoints.md](doc/api_endpoints.md):
- review `/bg (GET)`, `/bg (POST)`, `/clear`
- add `/clear/all`
- handle todos in file
- write short section introductionsreview and amend [api_endpoints.md](doc/api_endpoints.md):
- review `/bg (GET)`, `/bg (POST)`, `/clear`
- add `/clear/all`
- handle todos in file
- write short section introductionsVersion 1.0https://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/28Force errors to be JSON2021-06-08T15:42:32ZSiebers, MichaelForce errors to be JSONThe http server library decides automatically if errors should be returned as formatted HTML or as JSON. This decision is made in `http_json:prefer_json/1`.
We always want JSON returns. However, we *may* get HTML returns, for example if...The http server library decides automatically if errors should be returned as formatted HTML or as JSON. This decision is made in `http_json:prefer_json/1`.
We always want JSON returns. However, we *may* get HTML returns, for example if the request does not contain an `Accept` header. Can we force the library to return JSON?Version 1.0Siebers, MichaelSiebers, Michaelhttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/40Bump version number2021-05-13T11:47:31ZSiebers, MichaelBump version numberChange version number in code and documentationChange version number in code and documentationVersion 1.0https://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/56Cleanup2021-05-13T11:43:50ZSiebers, MichaelCleanupSmall tasks to be done before bumping the version number:
- change pldoc alias from `__API__` to `_API_` (consistent with default aliases)
- move `version.pl` to root directory (more prominent position)
- export version number under oth...Small tasks to be done before bumping the version number:
- change pldoc alias from `__API__` to `_API_` (consistent with default aliases)
- move `version.pl` to root directory (more prominent position)
- export version number under other name (`this_version/1` is rather uncommon), or export `api_version//0` instead
- remove mockups
- remove unused predicates?
- define and use location `background`?
- verify schemata
- provide curls?Version 1.0Siebers, MichaelSiebers, Michaelhttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/49describe module theory_bg2021-05-13T11:30:31ZSiebers, Michaeldescribe module theory_bgWrite developer documentation for module theory_bg in [module_theory_bg.md](doc/module_theory_bg.md).Write developer documentation for module theory_bg in [module_theory_bg.md](doc/module_theory_bg.md).Version 1.0Siebers, MichaelSiebers, Michaelhttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/43Write module description for web_api2021-05-13T11:30:31ZSiebers, MichaelWrite module description for web_apiReword structured PLDoc comment in `/src/web_api.pl`.Reword structured PLDoc comment in `/src/web_api.pl`.Version 1.0https://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/46write documentation overview2021-05-13T11:30:31ZSiebers, Michaelwrite documentation overviewwrite / amend the documentation's [landing page](doc/overview.md)write / amend the documentation's [landing page](doc/overview.md)Version 1.0https://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/48describe module types2020-12-19T04:18:55ZSiebers, Michaeldescribe module typesWrite developer documentation for module types in [module_types.md](doc/module_types.md).Write developer documentation for module types in [module_types.md](doc/module_types.md).Version 1.0Siebers, MichaelSiebers, Michaelhttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/54review readme.md2020-12-19T04:18:55ZSiebers, Michaelreview readme.mdRevise main [readme.md](readme.md):
- requirements (SWI-Prolog 8.2.2.)
- short intro how to start server (without arguments or only with `--port`)
- refer to documentation server by the software itselfRevise main [readme.md](readme.md):
- requirements (SWI-Prolog 8.2.2.)
- short intro how to start server (without arguments or only with `--port`)
- refer to documentation server by the software itselfVersion 1.0Siebers, MichaelSiebers, Michaelhttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/50describe module web_api2020-12-19T04:18:55ZSiebers, Michaeldescribe module web_apiWrite developer documentation for module web_api in [module_web_api.md](doc/module_web_api.md).Write developer documentation for module web_api in [module_web_api.md](doc/module_web_api.md).Version 1.0Siebers, MichaelSiebers, Michaelhttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/37Refactor endpoints2020-12-13T15:13:09ZSiebers, MichaelRefactor endpointsFor naming consistency I propose the following new endpoint names for POST requests:
| New Endpoint | Old Endpoint
|-----|-----|
|`/bg/add` | `/bg` |
|`/bg/remove` | `/clear` |
|`/bg/clear` | `/clear/all` |
The functionally of GET...For naming consistency I propose the following new endpoint names for POST requests:
| New Endpoint | Old Endpoint
|-----|-----|
|`/bg/add` | `/bg` |
|`/bg/remove` | `/clear` |
|`/bg/clear` | `/clear/all` |
The functionally of GET requests to `/bg` should be kept.
# Rationale
All endpoints working on background knowledge work on prefix `/bg`. The suffixes `/add`, `/remove`, and `/clear` convey their meaning more concisely than the original paths. The GET request to `/bg` is clearly separated from other requests.Version 1.0Sebastian SeufertSebastian Seuferthttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/25Describe project2020-12-12T19:06:59ZSiebers, MichaelDescribe projectGive the GitLab project a telling name, maybe provide additional information / linksGive the GitLab project a telling name, maybe provide additional information / linksVersion 1.0Siebers, MichaelSiebers, Michaelhttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/4Design server responses for "unexplainable" atoms.2020-12-10T18:35:59ZSiebers, MichaelDesign server responses for "unexplainable" atoms.Currently, explain/4 succeeds only if the atom to explain is true and an explanation can be constructed. For the first part this is intended: if the atom is false an "explanation why this is true" does not make sense. However, what is th...Currently, explain/4 succeeds only if the atom to explain is true and an explanation can be constructed. For the first part this is intended: if the atom is false an "explanation why this is true" does not make sense. However, what is the desired server response in that case? It probably should not be a 500, since there is no server-side error as such. Maybe a 200 with no payload?
What about the second part? When no explanation can be constructed for a true atom this is indeed an error. However, this probably should only happen if the domain designer made a mistake (e.g., forgot an explanation template). So this is probably also no 500.
Both errors should be distinguishable by the client.Version 1.0Sebastian SeufertSebastian Seuferthttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/31Document allowed characterpatterns for abs_path2020-12-10T18:07:35ZSebastian SeufertDocument allowed characterpatterns for abs_pathEither as schema or as regular expression.
@michael.siebers since this is related to your typechecking, where to best document this?Either as schema or as regular expression.
@michael.siebers since this is related to your typechecking, where to best document this?Version 1.0Siebers, MichaelSiebers, Michaelhttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/24Document theory_common and theory_templates2020-12-04T19:40:05ZSiebers, MichaelDocument theory_common and theory_templatesDescribe ...
- [x] the idea behind predicates in `theory_common.pl`
- [x] where these predicates are (or might be) used
- [x] the format of explanation templates
- [x] how to load explanation templates
- [x] where explanation templates a...Describe ...
- [x] the idea behind predicates in `theory_common.pl`
- [x] where these predicates are (or might be) used
- [x] the format of explanation templates
- [x] how to load explanation templates
- [x] where explanation templates are usedVersion 1.0https://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/41Contradicting returns of `/irrelevant/file` and `/explain`2020-12-04T19:38:07ZSiebers, MichaelContradicting returns of `/irrelevant/file` and `/explain`Given the example background knowledge, `/irrelevant/file` reports `/A/B/Filename2.exe` to be irrelevant and `/A/B/Filename.exe`to be not irrelevant. However, retrieving an explanation for `/A/B/Filename.exe` succeeds while requesting an...Given the example background knowledge, `/irrelevant/file` reports `/A/B/Filename2.exe` to be irrelevant and `/A/B/Filename.exe`to be not irrelevant. However, retrieving an explanation for `/A/B/Filename.exe` succeeds while requesting an explanation for `/A/B/Filename2.exe` results in a Bad Request response as `/A/B/Filename2.exe` is not irrelevant.Version 1.0Siebers, MichaelSiebers, Michaelhttps://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/38Harmonize internal and extermal representation of items2020-12-04T19:38:07ZSiebers, MichaelHarmonize internal and extermal representation of items_The described status quo assumes !13 has been merged. Consequently, this issue should only be attacked after said merge._
# Current situation
The external (JSON) representation of files and directories must have the property "type" wit..._The described status quo assumes !13 has been merged. Consequently, this issue should only be attacked after said merge._
# Current situation
The external (JSON) representation of files and directories must have the property "type" with a value of `"file"` or `"directory"`, respectively. The internal (dict) representation does not have this key, but the tag if the dict is either `'file'` or `'directory'`.
When receiving external representations (via `/bg` POST):
- the external representation is read into a dict (where the tag is a variable)
- it is checked if the "type" key is present with a valid value (done before transformation to give meaningful error messages)
- the "type" key is removed from the dict
- the dict's tag is unified with the value of type
When sending external representations (via `/bg` Get):
- the internal representation is retrieved from background knowledge
- it is send as is (This a bug, as we claim that our result conforms to the input specification but we send no "type" property).
# Solution
Either
1. we add the "type" property/key before sending out internal representations,
2. we change our internal representation to include the type in addition to the tag value, or
3. we change our internal representation to include the type but use a uniform tag, for example `item`.Version 1.0https://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/39Decide on xxx_time semantics2020-12-04T18:17:58ZSiebers, MichaelDecide on xxx_time semanticsIn `irrelevance_common.pl`, `creation_time/2` works as (+,-), other `xxx_time/2` are implemented as (?,?).
The tests for all of these predicates are commented to test (+,+), (+,-), and (-,+). But actually only (+,+) and (+,-) is tested!In `irrelevance_common.pl`, `creation_time/2` works as (+,-), other `xxx_time/2` are implemented as (?,?).
The tests for all of these predicates are commented to test (+,+), (+,-), and (-,+). But actually only (+,+) and (+,-) is tested!Version 1.0https://gitlab.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/-/issues/33Validate JSON input and throw exceptions2020-12-04T17:58:19ZSiebers, MichaelValidate JSON input and throw exceptionsOnly for the `/irrelevant/file` and the `/explain` endpoint, the JSON input is validated. And only these two endpoints throw appropriate exceptions (c.f. !6). These practices should be rolled out to the other endpoints:
- [ ] ~~`/`~~
- ...Only for the `/irrelevant/file` and the `/explain` endpoint, the JSON input is validated. And only these two endpoints throw appropriate exceptions (c.f. !6). These practices should be rolled out to the other endpoints:
- [ ] ~~`/`~~
- [ ] ~~`/add`~~
- [ ] ~~`/remove`~~
- [ ] ~~`/query`~~
- [x] `/state`
- [x] `/bg`
- [x] POST requests (c.f. #21)
- [x] GET requests
- [x] `/clear`
- [x] `/clear/all`
Some of these tasks might be done more easy after #27 is solved.Version 1.0Siebers, MichaelSiebers, Michael