improve route and right specification by Martin187187 · Pull Request #70 · admin-shell-io/aas-specs-security

Martin187187 · 2026-04-08T12:35:31Z

closes #58, #56

+This work is licensed under a [Creative Commons Attribution 4.0 International License](
+https://creativecommons.org/licenses/by/4.0/).
+
+SPDX-License-Identifier: CC-BY-4.0


+
+////
+
+= Examples of ROUTEs and HTTP requests


+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.


+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.


@@ -0,0 +1,63 @@
+@startuml


+    rectangle "Patch" as V_PATCH
+    rectangle "Put" as V_PUT
+    rectangle "Post" as V_POST
+    rectangle "GetAll" as V_GETALL


+representations.
+end note
+
+@enduml


BirgitBoss · 2026-04-08T14:14:14Z

+V_DELETE --> H_DELETE
+
+note bottom of V_GETALL
+Examples in AAS Part 2 also use GET


GET? it points to "GetAll". I would remove the comment and explain it in the text only

i removed this comment.

BirgitBoss · 2026-04-08T14:16:05Z

+
+[source,http]
+----
+POST /api/v3/shells HTTP/1.1


why is it important to add HTTP/1.1?

you are right. this information is unnecessary. i removed it.

BirgitBoss · 2026-04-08T14:17:39Z

+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


It was not clear for me from the structure that you assume that the examples in this section all require CREATE Rights. Please add as sentence at the beginning, similar to other sections.

I added a leading sentence before each RIGHT example section

BirgitBoss · 2026-04-08T14:19:47Z

+POST /api/v3/shells HTTP/1.1
+----
+
+Example 2: create a new submodel at a client-addressable route by PUT if the addressed submodel does not yet exist.


why is it important to sometimes add "client-addressable route" and sometimes just "use collection route" and not "client-addressable collection route"?

Focus is on the RIGHTs and not on the route paths, so i removed this unnecessary information

BirgitBoss · 2026-04-08T14:20:07Z

+
+=== CREATE
+
+Example 1: create a new AAS in the repository by POST to a collection route.


is "collection route" a technical term? We did not use it so far, do we?

i removed it.

BirgitBoss · 2026-04-08T14:26:04Z

+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.
+


I expected examples like

ACCESSRULE: ATTRIBUTES: GLOBAL(ANONYMOUS) RIGHTS: CREATE UPDATE ACCESS: ALLOW OBJECTS: ROUTE "/shells" ROUTE "/submodels/*"

because it is easier from an example to see what exactly to write as value for ROUTE - is my example correct? It could also be added to the other example file.

So rule above would allow me to execute POST /api/v3/shells and PUT /api/v3/shells as well as POST /api/v3/submodels PUT /api/v3/submodelsand POST /api/v3/submodels/{submodelIdentifier} and so on

Your example is correct. But be aware that for post {submodelIdentifier} is not needed and for PUT it is needed.
So correct endpoints would be:

POST /api/v3/shells

PUT /api/v3/shells/{aasIdentifier}

POST /api/v3/submodels

PUT /api/v3/submodels/{submodelIdentifier}

BirgitBoss

approved although I wish for another ACCESSRULE example and had some questions

Martin187187

Thank you @BirgitBoss for your feedback. I answered your questions and applied all your remarks as they were all reasonable!

Martin187187 · 2026-04-09T07:05:35Z

+V_DELETE --> H_DELETE
+
+note bottom of V_GETALL
+Examples in AAS Part 2 also use GET


i removed this comment.

Martin187187 · 2026-04-09T10:54:57Z

+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.
+


Your example is correct. But be aware that for post {submodelIdentifier} is not needed and for PUT it is needed.
So correct endpoints would be:

POST /api/v3/shells

PUT /api/v3/shells/{aasIdentifier}

POST /api/v3/submodels

PUT /api/v3/submodels/{submodelIdentifier}

Martin187187 · 2026-04-09T11:06:38Z

+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


I added a leading sentence before each RIGHT example section

Martin187187 · 2026-04-09T11:07:25Z

+
+=== CREATE
+
+Example 1: create a new AAS in the repository by POST to a collection route.


i removed it.

Martin187187 · 2026-04-09T11:07:54Z

+
+[source,http]
+----
+POST /api/v3/shells HTTP/1.1


you are right. this information is unnecessary. i removed it.

Martin187187 · 2026-04-09T11:10:05Z

+POST /api/v3/shells HTTP/1.1
+----
+
+Example 2: create a new submodel at a client-addressable route by PUT if the addressed submodel does not yet exist.


Focus is on the RIGHTs and not on the route paths, so i removed this unnecessary information

+For example, GET may correspond to READ for full content access or VIEW for reference-only or existence-only access.
+Search-style read operations may also use POST in specific interfaces.
+For endpoints with create-or-replace or upsert semantics, the required right depends on whether the addressed resource already exists.
+For example, `PUT /api/v3/submodels/{submodelIdentifier}` requires CREATE if the addressed submodel does not yet exist and UPDATE if it already exists.


+Search-style read operations may also use POST in specific interfaces.
+For endpoints with create-or-replace or upsert semantics, the required right depends on whether the addressed resource already exists.
+For example, `PUT /api/v3/submodels/{submodelIdentifier}` requires CREATE if the addressed submodel does not yet exist and UPDATE if it already exists.
+The same principle applies to endpoint-specific POST operations such as `POST /api/v3/lookup/shells/{aasIdentifier}` if the endpoint creates the addressed resource when absent and updates it when present.


+
+=== 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.


improve route and right specification

c313b27

github-advanced-security AI found potential problems Apr 8, 2026

View reviewed changes

add link to examples

78e9182

BirgitBoss reviewed Apr 8, 2026

View reviewed changes

Comment thread documentation/IDTA-01004/modules/ROOT/pages/annex/route-examples.adoc Outdated

BirgitBoss approved these changes Apr 8, 2026

View reviewed changes

clarification of examples & corrected attributes in urls

9fc6f43

Martin187187 commented Apr 9, 2026

View reviewed changes

github-advanced-security AI found potential problems Apr 9, 2026

View reviewed changes

Martin187187 merged commit 6593f96 into admin-shell-io:IDTA-01004-3-1_Working Apr 16, 2026
2 checks passed


		=== CREATE

		Example 1: create a new AAS in the repository by POST to a collection route.


		=== 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.

Conversation

Martin187187 commented Apr 8, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BirgitBoss Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

BirgitBoss left a comment

Choose a reason for hiding this comment

Uh oh!

Martin187187 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

BirgitBoss Apr 8, 2026 •

edited

Loading