Examples of ROUTEs and HTTP requests This annex is informative. It gives concrete examples for RIGHTS and ROUTE objects using AAS Part 2 HTTP/REST path templates. Unless stated otherwise, the examples use the server base URL https://admin-shell.io/api/v3/ as published in the AAS Part 2 OpenAPI descriptions. Only the URL path is relevant for ROUTE matching. Rights, operation verbs and HTTP methods The following diagram illustrates one possible relation between abstract rights, operation verbs and HTTP methods. It is an example to support the interpretation of the normative mapping in access-rule-model.adoc#table-rights-to-verbs. Example requests by right The following requests use real path templates from the published AAS Part 2 OpenAPI descriptions. They are representative examples for access control decisions on ROUTE objects. For client-addressable routes with create-or-replace or upsert semantics, the required right depends on whether the addressed resource already exists. In the examples below, PUT /api/v3/submodels/{id} and POST /api/v3/lookup/shells/{someencodedid} therefore appear under both CREATE and UPDATE with different preconditions. CREATE Here are endpoints that can need CREATE rights to create new resources or entries in the repository or registry. PUT endpoints with create-or-replace semantics can require UPDATE instead of CREATE rights if the addressed resource already exists. Example 1: create a new AAS in the repository by POST. POST /api/v3/shells Example 2: create a new submodel at a route by PUT if the addressed submodel does not yet exist. PUT /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU Example 3: create a new submodel element in a collection by POST. POST /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU/submodel-elements Example 4: create a lookup entry by POST if the addressed entry does not yet exist. POST /api/v3/lookup/shells/someencodedid READ Here are endpoints that can need READ rights to access existing resources or entries in the repository or registry. VIEW right can be used as an alternative for GetAll endpointsif only existence information, references, identifiers, or descriptor entries shall be accessible. Example 1: read all AAS objects. GET /api/v3/shells?limit=50 Example 2: read one submodel. GET /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU Example 3: read one submodel element by path. GET /api/v3/submodel/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA/submodel-elements/Identification/ManufacturerName Example 4: read all shell descriptors from the registry. GET /api/v3/shell-descriptors Example 5: resolve AAS IDs through discovery. This is an example of a read-like search operation implemented as POST. POST /api/v3/lookup/shellsByAssetLink UPDATE Here are endpoints that can need UPDATE rights to modify existing resources or entries in the repository or registry. For client-addressable routes with create-or-replace semantics, CREATE rights can be sufficient if the addressed resource does not yet exist. Example 1: replace an existing AAS resource by PUT. PUT /api/v3/shells/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA Example 2: replace an existing submodel at a client-addressable route by PUT if the addressed submodel already exists. PUT /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU Example 3: partially update a submodel by PATCH. PATCH /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU Example 4: update the value-only representation of a submodel element. PATCH /api/v3/submodel/submodel-elements/Identification/ManufacturerName/$value Example 5: update an AAS descriptor in the registry. PUT /api/v3/shell-descriptors/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA Example 6: update a lookup entry by POST if the addressed entry already exists. POST /api/v3/lookup/shells/someencodedid DELETE Here are endpoints that can need DELETE rights to delete existing resources or entries in the repository or registry. Example 1: delete a submodel from the repository. DELETE /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA Example 2: delete a submodel element by path. DELETE /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA/submodel-elements/Identification/ManufacturerName Example 3: delete a shell descriptor from the registry. DELETE /api/v3/shell-descriptors/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA EXECUTE Here are endpoints that can need EXECUTE rights to invoke operations on the repository or registry. Example 1: synchronously invoke an Operation. POST /api/v3/submodel/submodel-elements/Reset/invoke Example 2: asynchronously invoke an Operation. POST /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9tYWludGVuYW5jZQ/submodel-elements/Reset/invoke-async Example 3: retrieve the status of an asynchronous invocation. GET /api/v3/submodel/submodel-elements/Reset/operation-status/4a2a7aaf-6f44-4f88-bba2-0b0d2d3e7a10 VIEW VIEW is not bound to a dedicated HTTP method. In HTTP/REST APIs it is usually enforced on GET operations that only expose existence information, references, identifiers, or descriptor entries. Example 1: retrieve references instead of full resource content. GET /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU/$reference Example 2: retrieve submodel references of an AAS. GET /api/v3/shells/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA/submodel-refs Example 3: retrieve descriptor entries without accessing the hosted AAS content itself. GET /api/v3/shell-descriptors Notes for access rule authors ROUTE literals should be defined against stable path families such as /shells/, /submodels/, /shell-descriptors/ or /lookup/ if authorization is intended for complete interfaces. Exact ROUTE literals such as /submodel/submodel-elements/Reset/invoke are useful for single sensitive operations.