From 96d3f7d8099332c3b66f87146072395b60517360 Mon Sep 17 00:00:00 2001
From: Paul Gerber
Date: Wed, 26 Aug 2026 21:38:39 +0200
Subject: [PATCH 1/5] Implement `GET`/`PUT`/`DELETE` for
`/shells/asset-information/thumbnail`
Currently, server endpoint `/asset-information/thumbnail`,
methods=["GET", "PUT", "DELETE"], endpoint=self.not_implemented is
not implemented.
According to the AAS Repository Service OpenAPI Specification, the
endpoint should return, replace or delete the thumbnail file of a
selected AAS.
This issue specifies #439.
This change implements `GET`, `PUT` and `DELETE` for
`/shells/{aasIdentifier}/asset-information/thumbnail` according to
the specification. `GET` returns the thumbnail file referenced by
`AssetInformation.default_thumbnail`. `PUT` accepts a
`multipart/form-data` upload (`fileName` and `file`), stores it via
the file store, and updates `default_thumbnail` accordingly, removing
the previous thumbnail file if the path changes. `DELETE` removes the
stored file and clears `default_thumbnail`. All three reject external
(non-local) thumbnail references, since the server cannot serve or
manage files it does not store itself.
Fixes #493
---
server/app/interfaces/repository.py | 76 +++++++++++++++++++++++++++--
1 file changed, 73 insertions(+), 3 deletions(-)
diff --git a/server/app/interfaces/repository.py b/server/app/interfaces/repository.py
index fc7b4b0a0..f1234f6e8 100644
--- a/server/app/interfaces/repository.py
+++ b/server/app/interfaces/repository.py
@@ -80,8 +80,18 @@ def __init__(
),
Rule(
"/asset-information/thumbnail",
- methods=["GET", "PUT", "DELETE"],
- endpoint=self.not_implemented,
+ methods=["GET"],
+ endpoint=self.get_aas_thumbnail,
+ ),
+ Rule(
+ "/asset-information/thumbnail",
+ methods=["PUT"],
+ endpoint=self.put_aas_thumbnail,
+ ),
+ Rule(
+ "/asset-information/thumbnail",
+ methods=["DELETE"],
+ endpoint=self.delete_aas_thumbnail,
),
Rule("/submodel-refs", methods=["GET"], endpoint=self.get_aas_submodel_refs),
Rule("/submodel-refs", methods=["POST"], endpoint=self.post_aas_submodel_refs),
@@ -587,6 +597,66 @@ def put_aas_asset_information(
self.object_store.commit(aas)
return response_t()
+ def get_aas_thumbnail(
+ self, request: Request, url_args: Dict, response_t: Type[APIResponse], **_kwargs
+ ) -> Response:
+ shell = self._get_shell(url_args)
+ thumbnail = shell.asset_information.default_thumbnail
+ if thumbnail is None or not thumbnail.path:
+ raise NotFound(f"{shell!r} has no default thumbnail set!")
+ if not thumbnail.path.startswith("/"):
+ raise BadRequest(f"{shell!r} references an external thumbnail: {thumbnail.path}")
+ bytes_io = io.BytesIO()
+ try:
+ self.file_store.write_file(thumbnail.path, bytes_io)
+ except KeyError:
+ raise NotFound(f"No thumbnail file found at path: {thumbnail.path}")
+ return Response(bytes_io.getvalue(), content_type=thumbnail.content_type or "application/octet-stream")
+
+ def put_aas_thumbnail(
+ self, request: Request, url_args: Dict, response_t: Type[APIResponse], **_kwargs
+ ) -> Response:
+ shell = self._get_shell(url_args)
+ filename = request.form.get("fileName")
+ if filename is None:
+ raise BadRequest("No 'fileName' specified!")
+ elif not filename.startswith("/"):
+ raise BadRequest(f"Given 'fileName' doesn't start with a slash (/): {filename}")
+
+ file_storage: Optional[FileStorage] = request.files.get("file")
+ if file_storage is None:
+ raise BadRequest("Missing file to upload")
+
+ old_thumbnail = shell.asset_information.default_thumbnail
+ new_path = self.file_store.add_file(filename, file_storage.stream, file_storage.mimetype)
+ if old_thumbnail is not None and old_thumbnail.path and old_thumbnail.path.startswith("/") \
+ and old_thumbnail.path != new_path:
+ try:
+ self.file_store.delete_file(old_thumbnail.path)
+ except KeyError:
+ pass
+
+ shell.asset_information.default_thumbnail = model.Resource(new_path, file_storage.mimetype)
+ self.object_store.commit(shell)
+ return response_t()
+
+ def delete_aas_thumbnail(
+ self, request: Request, url_args: Dict, response_t: Type[APIResponse], **_kwargs
+ ) -> Response:
+ shell = self._get_shell(url_args)
+ thumbnail = shell.asset_information.default_thumbnail
+ if thumbnail is None or not thumbnail.path:
+ raise NotFound(f"{shell!r} has no default thumbnail set!")
+ if not thumbnail.path.startswith("/"):
+ raise BadRequest(f"{shell!r} references an external thumbnail: {thumbnail.path}")
+ try:
+ self.file_store.delete_file(thumbnail.path)
+ except KeyError:
+ pass
+ shell.asset_information.default_thumbnail = None
+ self.object_store.commit(shell)
+ return response_t()
+
def get_aas_submodel_refs(
self, request: Request, url_args: Dict, response_t: Type[APIResponse], **_kwargs
) -> Response:
@@ -1029,4 +1099,4 @@ def delete_concept_description(
WSGIApp(create_full_example(), aasx.DictSupplementaryFileContainer()),
use_debugger=True,
use_reloader=True,
- )
+ )
\ No newline at end of file
From 997396c196c23ad0f33cc7f023bec854dfe91864 Mon Sep 17 00:00:00 2001
From: Paul Gerber
Date: Wed, 26 Aug 2026 21:49:47 +0200
Subject: [PATCH 2/5] Fix whitespace
---
server/app/interfaces/repository.py | 2 +-
server/test/.DS_Store | Bin 0 -> 8196 bytes
2 files changed, 1 insertion(+), 1 deletion(-)
create mode 100644 server/test/.DS_Store
diff --git a/server/app/interfaces/repository.py b/server/app/interfaces/repository.py
index f1234f6e8..fbf2d55df 100644
--- a/server/app/interfaces/repository.py
+++ b/server/app/interfaces/repository.py
@@ -1099,4 +1099,4 @@ def delete_concept_description(
WSGIApp(create_full_example(), aasx.DictSupplementaryFileContainer()),
use_debugger=True,
use_reloader=True,
- )
\ No newline at end of file
+ )
diff --git a/server/test/.DS_Store b/server/test/.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..c180929621a058fac70883d17b0cb2877e9480e9
GIT binary patch
literal 8196
zcmeHMU2GIp6u#fI&{;ar0a_`z1Dh^HzyfP2@}F$~6l|f`ZRxfYmf4+w4oqjt&g>Q}
zHI0cc0vew*{zaesA@ZQ&--{%QqK{flFvbUr#-9gG^ab_7GjnJ8Y3Y;1K%AS*J@?#m
z&b{}X`Ocl5En^JL1??WjY8hi9Jsy=Ssk=e*O%2*3DOYt1PP3Zd<8j@#ZDvbjHM`r;M>2ACi*328Vd;6_z|eG38R#`E%^qpC
z3zp{iwka+UBVr^YFB~0hXlzK-#~SZ#7^{zsZsg;}v9X9)6JN8rD|6T!vg{Mw9|U&-
zn?1?DlhZk8I>i?5Tv@8*+}9=NBC{%`*-CG^uU{I-$n%QiMdz?<*p{dXs6UjE8iZt8#LA+cbCCj^QoSmv;4|t|yx!
zO7}Z<-fi(0%gA!U(Yth7%P8utw4#$XXiLwqdXl4voSCy=$d^He~*|_Ck<$HxE;3U?V^eDSz3p7U#8S4dpt=?UZ-9Q3|1(2
zOWh9nAj&FNTrDM}?!$zKi0ts0wbDAJ$5gYr8Id)<&jx9e(p%*5kI3zOa;sFMq;vMr
z5V`0?_*|3HqU`gw?NA-Jb6B^$BV8aFxprTjqV##PCQb7Xw5WDrmC~;45arLserHh4
z>zyM6)QMpJK~ePIHO+ggwP}WHUlI0rLfNp22IT;~R-OuCy!2|~$(4KfarC32m%nmFpdDW-QsT%n0(SWd
zV%z1JoQ*(LTP`;Glgh@XS`sKs4K5YC&i4Lg0Lr_h6a$Y4LR&@coGHjWVHk7EoEV;qkV
z;!hIhpTLuN2G8O-!u`v51+U^XUMJMQgLm;hKEy{jk52;pe?#d18NWs0;~1%WHpzgFb4oMR{_`IKZt9=i;rBoM{@
Date: Wed, 26 Aug 2026 21:53:42 +0200
Subject: [PATCH 3/5] Remove accidentally committed .DS_Store
---
server/test/.DS_Store | Bin 8196 -> 0 bytes
1 file changed, 0 insertions(+), 0 deletions(-)
delete mode 100644 server/test/.DS_Store
diff --git a/server/test/.DS_Store b/server/test/.DS_Store
deleted file mode 100644
index c180929621a058fac70883d17b0cb2877e9480e9..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 8196
zcmeHMU2GIp6u#fI&{;ar0a_`z1Dh^HzyfP2@}F$~6l|f`ZRxfYmf4+w4oqjt&g>Q}
zHI0cc0vew*{zaesA@ZQ&--{%QqK{flFvbUr#-9gG^ab_7GjnJ8Y3Y;1K%AS*J@?#m
z&b{}X`Ocl5En^JL1??WjY8hi9Jsy=Ssk=e*O%2*3DOYt1PP3Zd<8j@#ZDvbjHM`r;M>2ACi*328Vd;6_z|eG38R#`E%^qpC
z3zp{iwka+UBVr^YFB~0hXlzK-#~SZ#7^{zsZsg;}v9X9)6JN8rD|6T!vg{Mw9|U&-
zn?1?DlhZk8I>i?5Tv@8*+}9=NBC{%`*-CG^uU{I-$n%QiMdz?<*p{dXs6UjE8iZt8#LA+cbCCj^QoSmv;4|t|yx!
zO7}Z<-fi(0%gA!U(Yth7%P8utw4#$XXiLwqdXl4voSCy=$d^He~*|_Ck<$HxE;3U?V^eDSz3p7U#8S4dpt=?UZ-9Q3|1(2
zOWh9nAj&FNTrDM}?!$zKi0ts0wbDAJ$5gYr8Id)<&jx9e(p%*5kI3zOa;sFMq;vMr
z5V`0?_*|3HqU`gw?NA-Jb6B^$BV8aFxprTjqV##PCQb7Xw5WDrmC~;45arLserHh4
z>zyM6)QMpJK~ePIHO+ggwP}WHUlI0rLfNp22IT;~R-OuCy!2|~$(4KfarC32m%nmFpdDW-QsT%n0(SWd
zV%z1JoQ*(LTP`;Glgh@XS`sKs4K5YC&i4Lg0Lr_h6a$Y4LR&@coGHjWVHk7EoEV;qkV
z;!hIhpTLuN2G8O-!u`v51+U^XUMJMQgLm;hKEy{jk52;pe?#d18NWs0;~1%WHpzgFb4oMR{_`IKZt9=i;rBoM{@
Date: Fri, 23 Oct 2026 11:50:46 +0200
Subject: [PATCH 4/5] server/README.md: Remove thumbnail from unimplemented
Previously, the "Currently Unimplemented" section of the server README
listed the `/shells/{aasIdentifier}/asset-information/thumbnail` route.
This change implements that route, so the entry is removed.
The section is also changed from a numbered list to bullet points.
This way, adding or removing an entry no longer means renumbering all
the entries after it.
---
server/README.md | 12 +++++-------
1 file changed, 5 insertions(+), 7 deletions(-)
diff --git a/server/README.md b/server/README.md
index 26e9d7690..6f6c7706b 100644
--- a/server/README.md
+++ b/server/README.md
@@ -121,22 +121,20 @@ The server can be accessed at http://localhost:8080/api/v3.1/ from your host sys
## Currently Unimplemented
Several features and routes are currently not supported:
-1. Correlation ID: Not implemented because it was deemed unnecessary for this server.
+- Correlation ID: Not implemented because it was deemed unnecessary for this server.
-2. Extent Parameter (`withBlobValue/withoutBlobValue`):
+- Extent Parameter (`withBlobValue/withoutBlobValue`):
Not implemented due to the lack of support in JSON/XML serialization.
-3. Route `/shells/{aasIdentifier}/asset-information/thumbnail`: Not implemented because the specification lacks clarity.
-
-4. Serialization and Description Routes:
+- Serialization and Description Routes:
- `/serialization`
- `/description`
These routes are not implemented at this time.
-5. Value, Path, and PATCH Routes:
+- Value, Path, and PATCH Routes:
- All `/…/value$`, `/…/path$`, and `PATCH` routes are currently not implemented.
-6. Operation Invocation Routes: The following routes are not implemented because operation invocation
+- Operation Invocation Routes: The following routes are not implemented because operation invocation
is not yet supported by the `basyx-python-sdk`:
- `POST /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/invoke`
- `POST /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/invoke/$value`
From a46f92c80276aba9b4a2df7b3c147ef88bc28165 Mon Sep 17 00:00:00 2001
From: Paul Gerber
Date: Thu, 19 Nov 2026 15:38:04 +0100
Subject: [PATCH 5/5] server: Test the thumbnail endpoints and accept uploads
without content type
---
server/app/interfaces/repository.py | 20 +-
.../test/interfaces/repository/test_shells.py | 182 ++++++++++++++++++
2 files changed, 197 insertions(+), 5 deletions(-)
diff --git a/server/app/interfaces/repository.py b/server/app/interfaces/repository.py
index fbf2d55df..24c25dde6 100644
--- a/server/app/interfaces/repository.py
+++ b/server/app/interfaces/repository.py
@@ -627,17 +627,27 @@ def put_aas_thumbnail(
if file_storage is None:
raise BadRequest("Missing file to upload")
+ # A part without a Content-Type header has an empty mimetype, but an empty ContentType is invalid
+ content_type = file_storage.mimetype or None
+ # Validate before the file store changes, so that invalid input leaves the current thumbnail intact
+ try:
+ thumbnail = model.Resource(filename, content_type)
+ except ValueError as e:
+ raise BadRequest(str(e)) from e
+ thumbnail.path = self.file_store.add_file(
+ filename, file_storage.stream, content_type or "application/octet-stream"
+ )
+
old_thumbnail = shell.asset_information.default_thumbnail
- new_path = self.file_store.add_file(filename, file_storage.stream, file_storage.mimetype)
+ shell.asset_information.default_thumbnail = thumbnail
+ self.object_store.commit(shell)
+ # Delete the previous file only once the shell no longer references it
if old_thumbnail is not None and old_thumbnail.path and old_thumbnail.path.startswith("/") \
- and old_thumbnail.path != new_path:
+ and old_thumbnail.path != thumbnail.path:
try:
self.file_store.delete_file(old_thumbnail.path)
except KeyError:
pass
-
- shell.asset_information.default_thumbnail = model.Resource(new_path, file_storage.mimetype)
- self.object_store.commit(shell)
return response_t()
def delete_aas_thumbnail(
diff --git a/server/test/interfaces/repository/test_shells.py b/server/test/interfaces/repository/test_shells.py
index 9ad41f694..81225132b 100644
--- a/server/test/interfaces/repository/test_shells.py
+++ b/server/test/interfaces/repository/test_shells.py
@@ -6,8 +6,10 @@
# SPDX-License-Identifier: MIT
import base64
+import io
import json
from typing import Iterable
+from unittest import mock
from app.util.converters import base64url_encode
from basyx.aas import model
@@ -436,6 +438,186 @@ def test_shell_asset_information_put(self, format_client: FormatClient):
retrieved_shell.asset_information.global_asset_id,
)
+ # ------------------------------------------------------------------ /shells//asset-information/thumbnail
+
+ def _shell_with_thumbnail(self, path: str = "/thumbnail.png") -> model.AssetAdministrationShell:
+ shell = create_example_asset_administration_shell()
+ shell.asset_information.default_thumbnail = (
+ model.Resource(path, "image/png") if path else None
+ )
+ self.object_store.add(shell)
+ return shell
+
+ def _stored_shell(self, shell_id: str) -> model.AssetAdministrationShell:
+ shell = self.object_store.get(shell_id)
+ assert isinstance(shell, model.AssetAdministrationShell)
+ return shell
+
+ @staticmethod
+ def thumbnail_path(shell: model.AssetAdministrationShell) -> str:
+ return f"/shells/{base64url_encode(shell.id)}/asset-information/thumbnail"
+
+ def test_shell_thumbnail_get(self):
+ shell = self._shell_with_thumbnail()
+ self.file_store.write_file.side_effect = lambda name, stream: stream.write(b"png-bytes")
+
+ response = self.client.get(self.thumbnail_path(shell))
+
+ self.assertEqual(200, response.status_code)
+ self.assertEqual("image/png", response.content_type)
+ self.assertEqual(b"png-bytes", response.data)
+ self.file_store.write_file.assert_called_once_with("/thumbnail.png", mock.ANY)
+
+ def test_shell_thumbnail_get_without_thumbnail_returns_404(self):
+ shell = self._shell_with_thumbnail(path="")
+
+ self.assert_error(self.client.get(self.thumbnail_path(shell)), 404)
+
+ def test_shell_thumbnail_get_external_thumbnail_returns_400(self):
+ shell = self._shell_with_thumbnail(path="https://example.org/thumbnail.png")
+
+ self.assert_error(self.client.get(self.thumbnail_path(shell)), 400)
+
+ def test_shell_thumbnail_get_missing_file_returns_404(self):
+ shell = self._shell_with_thumbnail()
+ self.file_store.write_file.side_effect = KeyError
+
+ self.assert_error(self.client.get(self.thumbnail_path(shell)), 404)
+
+ def test_shell_thumbnail_get_unknown_shell_returns_404(self):
+ response = self.client.get(
+ f"/shells/{base64url_encode('https://example.org/unknown')}/asset-information/thumbnail"
+ )
+
+ self.assert_error(response, 404)
+
+ def test_shell_thumbnail_put_success(self):
+ shell = self._shell_with_thumbnail(path="")
+ self.file_store.add_file.return_value = "/thumbnail.png"
+
+ response = self.client.put(
+ self.thumbnail_path(shell),
+ data={"fileName": "/thumbnail.png", "file": (io.BytesIO(b"png-bytes"), "thumbnail.png", "image/png")},
+ content_type="multipart/form-data",
+ )
+
+ self.assertEqual(204, response.status_code)
+ self.file_store.add_file.assert_called_once_with("/thumbnail.png", mock.ANY, "image/png")
+ thumbnail = self._stored_shell(shell.id).asset_information.default_thumbnail
+ assert thumbnail is not None
+ self.assertEqual("/thumbnail.png", thumbnail.path)
+ self.assertEqual("image/png", thumbnail.content_type)
+
+ def test_shell_thumbnail_put_replaces_the_previous_file(self):
+ shell = self._shell_with_thumbnail(path="/old.png")
+ self.file_store.add_file.return_value = "/new.png"
+
+ response = self.client.put(
+ self.thumbnail_path(shell),
+ data={"fileName": "/new.png", "file": (io.BytesIO(b"png-bytes"), "new.png", "image/png")},
+ content_type="multipart/form-data",
+ )
+
+ self.assertEqual(204, response.status_code)
+ self.file_store.delete_file.assert_called_once_with("/old.png")
+ thumbnail = self._stored_shell(shell.id).asset_information.default_thumbnail
+ assert thumbnail is not None
+ self.assertEqual("/new.png", thumbnail.path)
+
+ def test_shell_thumbnail_put_without_content_type_stores_none(self):
+ # A multipart part without a Content-Type header, as some clients send it
+ shell = self._shell_with_thumbnail(path="/old.png")
+ self.file_store.add_file.return_value = "/thumbnail.png"
+ body = (
+ b"--boundary\r\n"
+ b'Content-Disposition: form-data; name="fileName"\r\n\r\n'
+ b"/thumbnail.png\r\n"
+ b"--boundary\r\n"
+ b'Content-Disposition: form-data; name="file"; filename="thumbnail.png"\r\n\r\n'
+ b"png-bytes\r\n"
+ b"--boundary--\r\n"
+ )
+
+ response = self.client.put(
+ self.thumbnail_path(shell), data=body, content_type="multipart/form-data; boundary=boundary"
+ )
+
+ self.assertEqual(204, response.status_code)
+ thumbnail = self._stored_shell(shell.id).asset_information.default_thumbnail
+ assert thumbnail is not None
+ self.assertEqual("/thumbnail.png", thumbnail.path)
+ self.assertIsNone(thumbnail.content_type)
+ self.file_store.add_file.assert_called_once_with("/thumbnail.png", mock.ANY, "application/octet-stream")
+
+ def test_shell_thumbnail_put_invalid_file_name_keeps_the_previous_thumbnail(self):
+ # Longer than the 2048 characters a PathType may have
+ shell = self._shell_with_thumbnail(path="/old.png")
+ file_name = "/" + "a" * 2048
+
+ response = self.client.put(
+ self.thumbnail_path(shell),
+ data={"fileName": file_name, "file": (io.BytesIO(b"png-bytes"), "new.png", "image/png")},
+ content_type="multipart/form-data",
+ )
+
+ self.assert_error(response, 400)
+ self.file_store.add_file.assert_not_called()
+ self.file_store.delete_file.assert_not_called()
+ thumbnail = self._stored_shell(shell.id).asset_information.default_thumbnail
+ assert thumbnail is not None
+ self.assertEqual("/old.png", thumbnail.path)
+
+ def test_shell_thumbnail_put_missing_file_name_returns_400(self):
+ shell = self._shell_with_thumbnail(path="")
+
+ response = self.client.put(
+ self.thumbnail_path(shell),
+ data={"file": (io.BytesIO(b"png-bytes"), "thumbnail.png", "image/png")},
+ content_type="multipart/form-data",
+ )
+
+ self.assert_error(response, 400)
+
+ def test_shell_thumbnail_put_relative_file_name_returns_400(self):
+ shell = self._shell_with_thumbnail(path="")
+
+ response = self.client.put(
+ self.thumbnail_path(shell),
+ data={"fileName": "thumbnail.png", "file": (io.BytesIO(b"png-bytes"), "thumbnail.png", "image/png")},
+ content_type="multipart/form-data",
+ )
+
+ self.assert_error(response, 400)
+
+ def test_shell_thumbnail_put_missing_file_returns_400(self):
+ shell = self._shell_with_thumbnail(path="")
+
+ response = self.client.put(
+ self.thumbnail_path(shell), data={"fileName": "/thumbnail.png"}, content_type="multipart/form-data"
+ )
+
+ self.assert_error(response, 400)
+
+ def test_shell_thumbnail_delete(self):
+ shell = self._shell_with_thumbnail()
+
+ response = self.client.delete(self.thumbnail_path(shell))
+
+ self.assertEqual(204, response.status_code)
+ self.file_store.delete_file.assert_called_once_with("/thumbnail.png")
+ self.assertIsNone(self._stored_shell(shell.id).asset_information.default_thumbnail)
+
+ def test_shell_thumbnail_delete_without_thumbnail_returns_404(self):
+ shell = self._shell_with_thumbnail(path="")
+
+ self.assert_error(self.client.delete(self.thumbnail_path(shell)), 404)
+
+ def test_shell_thumbnail_delete_external_thumbnail_returns_400(self):
+ shell = self._shell_with_thumbnail(path="https://example.org/thumbnail.png")
+
+ self.assert_error(self.client.delete(self.thumbnail_path(shell)), 400)
+ self.file_store.delete_file.assert_not_called()
+
# ------------------------------------------------------------------ GET /shells//submodel-refs
@with_json_client