DotAAS Part 2: HTTP API #238
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
list werkzeug as a dependency in the readme
adapter.http: add custom identifier converter for werkzeug adapter.http: restructure routing map, add first submodel route adapter.http: refine imports
adapter._generic: add identifier URI encode/decode functions adapter.http: make api routes return ResponseData instead of the Response directly adapter.http: add Result + Message types + factory function
adapter.http: add request body parsing adapter.http: implement all remaining aas routes
- use stripped object serialization/deserialization - change response format (new spec always returns a result object)
adapter.http: remove old routes, add a few new aas and submodel routes
using the werkzeug.routing.MapAdapter url builder
Requests to URIs with a trailing slash will now be redirected to the respective URI without trailing slash. e.g. GET /aas/$identifier/ -> GET /aas/$identifier A redirect will only be set if the respective URI without trailing slash exists and the current request method is valid for the new URI. Historically, the trailing slash was only present when the requested resource was a directory. In our case the resources don't work like directories, in the sense, that each resource doesn't even list possible subsequent resources. So because our resources don't behave like directories, they shouldn't have a trailing slash.
for better error messages
because that's default anyways
to stay consistent with the rest of this library
add IdShortPathConverter and helper functions
change type check from `not A is B` to `A is not B` for better readability
… attributes like statement, annotation and value
adapter.http: remove excess blank line
merge `main` in `feature/http_api`
`AbstractSupplementaryFileContainer` and `DictSupplementaryFileContainer` are extended by a `delete_file()` method, that allows deleting files from them. Since different files may have the same content, references to the files contents in `DictSupplementaryFileContainer._store` are tracked via `_store_refcount`. A files contents are only deleted from `_store`, if all filenames referring to these these contents are deleted, i.e. if the refcount reaches 0.
DeprecationWarning: datetime.datetime.utcnow() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.now(datetime.UTC)
This change makes use of the `SupplementaryFileContainer` interface of the AASX adapter. It allows the API to operate seamlessly on AASX files, including the contained supplementary files, without having to access the filesystem. Furthermore, the support for the modification of `Blob` values is removed (the spec prohibits it).
…n_warning adapter.http: fix a `DeprecationWarning`
adapter.http: allow retrieving and modifying `File` attachments via API
adapter.http: allow changing the API base path
This check was intended to return 501 instead of 404 for routes that haven't been implemented. However, we explicitly implement these routes to return 501 now anyway, returning 501 for all other paths would be semantically incorrect anyway and the check never worked.
Merge/main in feature http api
Werkzeug 3.0.3 contains a fix for [1], so by requiring at least 3.0.3, we can remove unnecessary 'type: ignore' comments from the http adapter. [1]: pallets/werkzeug#2836
Remove 'type: ignore' comments now that we require werkzeug >=3.0.3 [1]. Furthermore, fix the type hint of `WSGIApp._get_slice()` and make two other 'type: ignore' comments more explicit. [1]: pallets/werkzeug#2836
adapter.http: remove and improve `type: ignore` comments
…t_implemented_check
…t_implemented_check adapter.http: remove nonfunctional 'Not Implemented' check
This removes trailing slashes (and redirects to paths with trailing slashes) from the API and makes it compatible with the PCF2 showcase and other webapps. Previously, all routes were implemented with a trailing slash, e.g. `/submodels/` instead of `/submodels`. While the API spec only specifies the routes without a trailing slash, this has the advantage of being compatible with requests to the path with a trailing slash and without trailing slash, as werkzeug redirects requests to the slash-terminated path, if available. However, this poses a problem with browsers that make use of [CORS preflight requests][1] (e.g. Chromium-based browsers). Here, before doing an actual API request, the browser sends an `OPTIONS` request to the path it wants to request. This is done to check potential CORS headers (e.g. `Access-Control-Allow-Origin`) for the path, without retrieving the actual data. Our implementation doesn't support `OPTIONS` requests, which is fine. After the browser has received the response to the preflight request (which may or may not have been successful), it attempts to retrieve the actual data by sending the request again with the correct request method (e.g. `GET`). With our server this request now results in a redirect, as we redirect to the path with a trailing slash appended. This is a problem, as the browser didn't send a CORS preflight request to the path it is now redirected to. It also doesn't attempt to send another CORS preflight request, as it already sent one, with the difference being the now slash-terminated path. Thus, following the redirect is prevented by CORS policy and the data fails to load. By making the routes available via non-slash-terminated paths we avoid the need for redirects, which makes the server compatible with webapps viewed in browsers that use preflight requests. Requests to slash-terminated paths will no longer work (they won't redirect to the path without trailing slash). This shouldn't be a problem though, as the API is only specified without trailing slashes anyway.
adapter.http: remove unnecessary generator expression
adapter.http: remove trailing slashes from routes
This adds a module docstring to `adapter.http`, that details which features from the Specification of the Asset Administration Shell Part 2 (API) were not implemented.
s-heppner
approved these changes
Aug 16, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds the
httpadapter, an implementation of the HTTP AAS and Submodel Repository Interfaces of "Details of the Asset Administration Shell Part 2":Partially implements #207
General TODOs:
limitundcursorquery parameter) (adapter.http: implement the pagination rwth-iat/basyx-python-sdk#35)Message-> we're not sure how to implement this feature of the APIcorrelationId(whatever that is)/aassubmount of AAS routes (yay, they changed it!) (adapter.http: remove/aassubmount from AAS repository rwth-iat/basyx-python-sdk#9)extentparameter (withBlobValue/withoutBlobValue)asset-informationroutes to a submount (adapter.http: moveasset-informationroutes to a submount rwth-iat/basyx-python-sdk#28)/api/v1to/api/v3.0(adapter.http: update base URL from/api/v1to/api/v3.0rwth-iat/basyx-python-sdk#10)/constraintsroutes of the submodel API, rename to/qualifiersor remove?Discussion 27.03.2024: rename to
/qualifiers(adapter.http: fix qualifier routes rwth-iat/basyx-python-sdk#29)IdShortPathConverter(model.base: moveid_shortvalidation to separate function #239)IdentifierConvertertoBase64URLConverter,identifiertobase64url(after adapter.http: fix qualifier routes rwth-iat/basyx-python-sdk#29 has been merged) (adapter.http: renameIdentifierConvertertoBase64URLConverterrwth-iat/basyx-python-sdk#30)_get_submodels()and_get_submodel()for AAS routes (after adapter.http: AASSpecificAssetIdfiltering rwth-iat/basyx-python-sdk#23 has been merged) (adapter.http: refactor AAS retrieval rwth-iat/basyx-python-sdk#31)AAS Routes @hadijannat
/shellsGETassetIdsquery parameter (adapter.http: AASSpecificAssetIdfiltering rwth-iat/basyx-python-sdk#23)POSTGET/shells/$reference(adapter.http: implement the AAS reference routes rwth-iat/basyx-python-sdk#34)/shells/{aasIdentifier}GETPUTDELETEGET/shells/{aasIdentifier}/$reference(adapter.http: implement the AAS reference routes rwth-iat/basyx-python-sdk#34)/shells/{aasIdentifier}/asset-informationGETPUT/shells/{aasIdentifier}/asset-information/thumbnailGETPUTDELETE/shells/{aasIdentifier}/submodel-refscurrently implemented as/submodels, needs to be renamed (adapter.http: update AAS submodel refs path andDELETEroute rwth-iat/basyx-python-sdk#24)GETPOSTDELETE/shells/{aasIdentifier}/submodel-refs/{submodelIdentifier}(adapter.http: update AAS submodel refs path andDELETEroute rwth-iat/basyx-python-sdk#24)GET/serializationGET/descriptionThe following routes assume you know the submodel identifier, why wouldn't you use the submodel repository instead? Maybe simply return a redirect to the submodel repository for these routes :D
/shells/{aasIdentifier}/submodels/{submodelIdentifier}/...-> REDIRECT (adapter.http: implement AAS API submodel routes via redirects rwth-iat/basyx-python-sdk#27)Submodel Routes @Frosty2500
/submodelsGETsemanticIdquery parameterPOSTGET/submodels/$metadata(adapter.http: implement submodel repo routes rwth-iat/basyx-python-sdk#22)GET/submodels/$valueGET/submodels/$reference(adapter.http: implement submodel repo routes rwth-iat/basyx-python-sdk#22)GET/submodels/$path/submodels/{submodelIdentifier}GETPUTPATCHDELETE/submodels/{submodelIdentifier}/$metadataGET(adapter.http: implement submodel repo routes rwth-iat/basyx-python-sdk#22)PATCH/submodels/{submodelIdentifier}/$valueGETPATCHGET/submodels/{submodelIdentifier}/$reference(adapter.http: implement submodel repo routes rwth-iat/basyx-python-sdk#22)GET/submodels/{submodelIdentifier}/$path/submodels/{submodelIdentifier}/submodel-elementsGETPOSTGET/submodels/{submodelIdentifier}/submodel-elements/$metadata(adapter.http: implement submodel repo routes rwth-iat/basyx-python-sdk#22)GET/submodels/{submodelIdentifier}/submodel-elements/$valueGET/submodels/{submodelIdentifier}/submodel-elements/$reference(adapter.http: implement submodel repo routes rwth-iat/basyx-python-sdk#22)GET/submodels/{submodelIdentifier}/submodel-elements/$path/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}GETPOSTPUTPATCHDELETE/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/$metadata(adapter.http: implement submodel repo routes rwth-iat/basyx-python-sdk#22)GETPATCH/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/$valueGETPATCHGET/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/$reference(adapter.http: implement submodel repo routes rwth-iat/basyx-python-sdk#22)GET/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/$path/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/attachment(adapter.http: implement the attachment routes rwth-iat/basyx-python-sdk#33)GETPUTDELETEGET/serializationGET/descriptionThe following routes invoke operations, which is currently not implemented in the basyx-python-sdk.
POST/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/invokePOST/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/invoke/$valuePOST/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/invoke-asyncPOST/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/invoke-async/$valueGET/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/operation-status/{handleId}GET/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/operation-results/{handleId}GET/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/operation-results/{handleId}/$value