[aaronzi]

Closes #495.

Clients should be able to use the /attachment endpoint without first checking whether a file is stored by the server or referenced by an external URL. For HTTP(S) URLs in File.value, this PR recommends 302 Found with the URL in the Location header. The same behavior applies to /thumbnail and AssetInformation.defaultThumbnail.path, as already implemented in BaSyx Go.

The redirect is a recommendation (should), not a requirement, because how a server obtains the content it returns is an implementation decision. A warning explains the risks of the alternatives: fetching URLs supplied through writable model data can expose the server to SSRF, and resolving locations outside the managed file storage can disclose files. Authorization is still checked before the content or the redirect URL is disclosed. Clients decide whether to follow the redirect under their own security policy and must not forward credentials intended for the AAS server to another origin. Managed files are still returned with 200 OK; missing locations or missing managed files return 404 Not Found.

The change adds the HTTP/REST explanation and an example, adds the generic status code RedirectionFound and its HTTP mapping, aligns the abstract payload definitions, and adds a shared redirect response with a required Location header to all 22 affected GET definitions across 11 service profiles and the combined API. It also updates the conformance cases and adds a V3.3 changelog entry. The existing write operations are unchanged.

This PR now targets IDTA-01002-3-3_working instead of IDTA-01002-3-2-1_working, since it changes behavior and is not a bugfix (see the discussion below).

Validation

• python tools/validate_spec_artifacts.py
• python tools/validate_multipart_uploads.py
• openapi-spec-validator passes for all 11 affected profiles and the combined API
• git diff --check

[BirgitBoss]

and what happens with a relative path?

[aaronzi]

That will stay as before -> Returns the thumbnail file

[BirgitBoss]

I think the new return codes must be added to https://industrialdigitaltwin.io/aas-specifications/IDTA-01002/v3.1.1/http-rest-api/http-rest-api.html#mapping-of-status-codes, I did not see this.

It seems these changes are not backward compatible, are they? It is not only a bugfix for 3.2 but also for 3.1 and 3.0

[aaronzi]

I think the new return codes must be added to https://industrialdigitaltwin.io/aas-specifications/IDTA-01002/v3.1.1/http-rest-api/http-rest-api.html#mapping-of-status-codes

thanks, I will add that.

t seems these changes are not backward compatible, are they? It is not only a bugfix for 3.2 but also for 3.1 and 3.0

I see two options here. We could either handle this as a bugfix or we could see it as a feature. If it's a bugfix, you are right, it should then also be added to 3.1 and 3.0. Alternatively, we could add this to a new branch/milestone 3.3. What would you say is the better way @BirgitBoss?

[sebastiankb]

from today's API meeting:

• is this really a bug fix? Since its changes the behavoir: Receiving a file vs a link of the file
• the expectation is, that always the server responses with a path location of the file:

1. relative path means, it is an embedded file that is hosted by the AAS server. In that case, the client can call the $attachment of the AAS element that returns the embedded file.
2. absolute path means, the client needs to download the file based on this path, it may be hosted external. It could do without $attachment call (like a normal file download). If the $attachment is used in combination with an absolute path to the (external) file, a redirect information can provided by the AAS server

[aaronzi]

It is not really a bugfix, that is true. I will open the PR again for the 3.3 working branch and do the necessary changes for that. Thanks for the feedback @sebastiankb

[mjacoby]

Using shall, i.e., making it mandatory, would mean the spec defines internal behavior/implementation of the server which I think is outside the scope of the spec.
I therefore recommend to change it to should with a big warning about the dangers when doing it diffrently.

[aaronzi]

Good point @mjacoby. How the server gets the content is an implementation detail, so I changed the redirect to a recommendation: for external HTTP(S) locations the server should return 302 Found. The "shall not fetch" and "resolve only against managed storage" requirements are gone. Instead there's a [WARNING] block covering the risks of the alternatives: server-side fetching can lead to SSRF (it also lists the usual protections, like allow-lists, blocking internal addresses and not forwarding credentials), and looking up locations outside the managed file storage can expose files. It also says that returning 302 avoids the fetch and is the recommended way.

I kept as "shall" only what a client can actually see: authorization is checked before the content or the redirect URL is revealed, managed files come back with 200, and missing files return 404. The conformance cases HTTP.file.002/003 now say SHOULD instead of MUST.