HTTP REST API for Protoplaster server mode

.github/docs-template/requirements.txt

@@ -1,2 +1,3 @@
 https://github.com/antmicro/antmicro-sphinx-utils/archive/main.zip
 pydantic==2.4.2 #2.5.0 causes AttributeError during sphinx execution
+sphinxcontrib-httpdomain

.github/docs-template/source/api.rst

@@ -0,0 +1,32 @@
+
+Protoplaster Server API Reference
+---------------------------------
+
+Error Handling
+~~~~~~~~~~~~~~
+
+Should an error occur during the handling of an API request, either because of incorrect request data or other endpoint-specific scenarios, the server will return an error structure containing a user-friendly description of the error.
+An example error response is shown below:
+
+.. sourcecode:: json
+
+   {
+      "error": "test start failed"
+   }
+
+
+Configs API
+~~~~~~~~~~~
+
+.. autoflask:: protoplaster.protoplaster:create_docs_app()
+   :modules: protoplaster.api.v1.configs
+   :undoc-static:
+   :order: path
+
+Test Runs API
+~~~~~~~~~~~~~
+
+.. autoflask:: protoplaster.protoplaster:create_docs_app()
+   :modules: protoplaster.api.v1.test_runs
+   :undoc-static:
+   :order: path

.github/docs-template/source/conf.py

@@ -37,6 +37,8 @@
 
 # If you need to add extensions just add to those lists
 extensions = default_extensions
+extensions.append('sphinxcontrib.autohttp.flask')
+extensions.append('sphinxcontrib.autohttp.flaskqref')
 myst_enable_extensions = default_myst_enable_extensions
 myst_fence_as_directive = default_myst_fence_as_directive
 

.github/docs-template/source/index.md

@@ -4,6 +4,7 @@
 :maxdepth: 2
 
 introduction
+api
 readme
 protoplaster
 report

.github/docs-template/source/introduction.md

@@ -2,7 +2,9 @@
 
 This documentation serves as an example of how individual projects documentation can look like.
 
-The second chapter contains information from the README file.
+The second chapter contains reference of remote API when running Protoplaster in server mode.
+
+The third chapter contains information from the README file.
 
 The last chapter is generated from the sample ``test.yml`` file which can be found in the README.
 Its purpose is to demonstrate the documentation generated to describe test procedures used in a project.

.github/scripts/latex.sh

@@ -2,12 +2,16 @@
 
 set -e
 
+apt-get update -qq
+DEBIAN_FRONTEND=noninteractive apt-get -y install --no-install-recommends git
+
 cd $(dirname $0)/../../docs
 
 python3 -m venv ./venv
 . ./venv/bin/activate
 
 pip3 install -r requirements.txt
+pip3 install ../
 
 cd build/latex
 LATEXMKOPTS='-interaction=nonstopmode' make

.github/scripts/sphinx.sh

@@ -8,6 +8,7 @@ python3 -m venv ./venv
 . ./venv/bin/activate
 
 pip3 install -r requirements.txt
+pip3 install ../
 
 make html latex
 

protoplaster/api/v1/__init__.py

@@ -0,0 +1,13 @@
+from flask import Blueprint
+
+import protoplaster.api.v1.configs
+import protoplaster.api.v1.test_runs
+
+
+def create_routes() -> Blueprint:
+    api_routes: Blueprint = Blueprint("protoplaster-api-v1", __name__)
+    api_routes.register_blueprint(
+        protoplaster.api.v1.configs.configs_blueprint)
+    api_routes.register_blueprint(
+        protoplaster.api.v1.test_runs.test_runs_blueprint)
+    return api_routes

protoplaster/api/v1/configs.py

@@ -0,0 +1,163 @@
+from flask import Blueprint
+
+configs_blueprint: Blueprint = Blueprint("protoplaster-configs", __name__)
+
+
+@configs_blueprint.route("/api/v1/configs")
+def fetch_configs():
+    """Fetch a list of configs
+
+    :status 200: no error
+
+    :>jsonarr string created: UTC datetime of config upload (RFC822)
+    :>jsonarr string name: config name
+
+    **Example Request**
+
+    .. sourcecode:: http
+
+        GET /api/v1/configs HTTP/1.1
+        Accept: application/json, text/javascript
+
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+
+        [
+          {
+            "name": "sample_config.yaml",
+            "created": "Mon, 25 Aug 2025 16:58:35 +0200",
+          }
+        ]
+    """  # noqa: E501
+    #TODO: Add implementation
+    return {}, 200
+
+
+@configs_blueprint.route("/api/v1/configs", methods=["POST"])
+def upload_config(scopes: list[str] = []):
+    """Upload a test config
+
+    :form file: yaml file with the test config
+
+    :status 200: no error, config was uploaded
+    :status 400: file was not provided
+
+    **Example Request**
+
+    .. sourcecode:: http
+
+        POST /api/v1/configs HTTP/1.1
+        Accept: */*
+        Content-Length: 4194738
+        Content-Type: multipart/form-data; boundary=------------------------0f8f9642db3a513e
+
+        --------------------------0f8f9642db3a513e
+        Content-Disposition: form-data; name="file"; filename="config.yaml"
+        Content-Type: application/octet-stream
+
+        <file contents>
+        --------------------------0f8f9642db3a513e--
+
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+    """  # noqa: E501
+    #TODO: Add implementation
+    return {}, 200
+
+
+@configs_blueprint.route("/api/v1/configs/<string:config_name>")
+def fetch_one_config():
+    """Fetch information about a config
+
+    :status 200: no error
+    :status 404: config does not exist
+
+    :>json string created: UTC datetime of config upload (RFC822)
+    :>json string config_name: config name
+
+    **Example Request**
+
+    .. sourcecode:: http
+
+        GET /api/v1/configs/sample_config.yaml HTTP/1.1
+        Accept: application/json, text/javascript
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+
+        {
+          "name": "sample_config.yaml",
+          "created": "Mon, 25 Aug 2025 16:58:35 +0200",
+        }
+    """  # noqa: E501
+    #TODO: Add implementation
+    return {}, 200
+
+
+@configs_blueprint.route("/api/v1/configs/<string:config_name>/file")
+def fetch_config_file():
+    """Fetch a config file
+
+    :status 200: no error
+    :status 404: config does not exist
+
+    :>file text/yaml: YAML config file
+
+    **Example Request**
+
+    .. sourcecode:: http
+
+        GET /api/v1/configs/sample_config.yaml/file HTTP/1.1
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: text/yaml
+        Content-Disposition: attachment; filename="sample_config.yaml"
+
+        base:
+          network:
+            - interface: enp14s0
+    """  # noqa: E501
+    #TODO: Add implementation
+    return {}, 200
+
+
+@configs_blueprint.route("/api/v1/configs/<string:name>", methods=["DELETE"])
+def delete_config(scopes: list[str] = []):
+    """Remove a test config
+
+    :param name: filename of the test config
+
+    :status 200: no error, config was removed
+    :status 404: file was not found
+
+    **Example Request**
+
+    .. sourcecode:: http
+
+        DELETE /api/v1/configs/sample_config.yaml HTTP/1.1
+
+    **Example Response**
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+    """  # noqa: E501
+    #TODO: Add implementation
+    return {}, 200