The Pragmatic Proof Algorithm (PPA) solves hypermedia API composition problems — in other words, it answers the question “which requests to execute in which sequence in order to achieve a goal given a set of hypermedia APIs?”. It was developed by Verborgh et al. and is described in detail in
Verborgh, Ruben, Dörthe Arndt, et al. (2017-01). “The Pragmatic Proof: Hypermedia API Composition and Execution”. In: Theory and Practice of Logic Programming 17.1, pp. 1–48. DOI: 10.1017/S1471068416000016.
This repository contains an implementation of what is described in the paper above with the aim of fully understanding it and reproducing its core results. Moreover, it includes examples that demonstrate the ability of the PPA to achieve declaratively formulated goals.
Get a local copy of the code in this repository by cloning or downloading a release. Then, install the dependencies using pipenv install and activate the resulting virtual environment with pipenv shell. Make sure that Node.js and the Docker engine are installed.
The implementation relies on the existence of a Docker image of the EYE reasoner. For building this image, get a local copy of the EYE-repository and execute docker build -t eye:latest . from within that directory.
The name of the image MUST to be communicated to the PPA through an ENVVAR. Furthermore, a timeout for the reasoner and other options CAN be set.
| Environment Variable | Description | Default Value |
|---|---|---|
|
The name of the Docker image for the EYE reasoner, e.g. |
— |
|
A threshold in seconds after which the EYE reasoner is timed out |
|
|
The minimum log level to be included in the logs. There exist additional levels |
|
The PPA-implementation can be used via a Command-Line Interface (CLI) as well as from Python source code.
The CLI is implemented using Invoke. List the available functionality using invoke --list and display the documentation for specific functionality using, for example, invoke --help run-example.
For using the PPA in Python, import and use the solve_api_composition_problem(..)-function, which returns 0 if successful and 1 to indicate failure.
Running the PPA-implementation requires a directory in which all files generated/retrieved during execution can be stored. Most of these files follow the naming scheme <iteration>_<init/pre/sub>_<what>.<extension> to facilitate understanding what happens in which order. For example, 00_pre_proof.n3 refers to the pre-proof generated in the first iteration and 01_sub_proof.n3 refers to the post-proof (sub for subsequent) generated during the second iteration.
There are two examples of using the PPA included in this repository. They can be executed via invoke run-example [--options].
-
Getting a Thumbnail of an Image — this is an implementation of the example used by Verborgh et al. to explain RESTdesc and the PPA in the corresponding scientific publications. The hypermedia API is implemented in
img_api/— refer to the README for details. The necessary inputs can be found in examples/image_resizing/. -
Simulating a Functional Mock-up Unit (FMU) — this instantiates and simulates an FMU representing a PV system using an instance of the hypermedia API-variant of https://github.com/UdSAES/simaas-api. The necessary inputs are provided in examples/simulation/.
-
❏ Replace exemplary FMU with one that doesn’t require a Dymola-license to execute (!) and assign proper license
-
❏ Document extension of PPA to deal with shapes for inputs
-
❏ …
-
❏ Fix unit tests currently skipped
-
❏ Link to paper iff it is accepted
-
❏ …
Feedback is very welcome! Please open an issue for questions, remarks and bug reports; or open a pull request if you want to improve something.
The code in this repository uses Semantic Versioning (semver) and follows the semver specification.
The Python code is formatted automatically using black and isort. JavaScript code and JSON documents inside img_api/ are formatted automatically according to JavaScript Standard Style using prettier-standard via npm run format.
There are some unit tests and API tests for the API providing thumbnails, implemented using pytest. The API tests require the ENVVAR API_ORIGIN to be set.
The source code is licensed under the MIT License. This is specified in the format suggested by the REUSE SOFTWARE-initiative — in short: SPDX IDs are included in every non-binary file and the license text can be found in ./LICENSES/.