Result Objects are not Type-Safe

[sebbader-sap]

What?

We're trying to improve the compatibility of assets between different organisations and technologies. Thus we should try to create APIs, that can be realized in at least the majority technologies. The strategy of modifying result structures via query parameters results in bad implementations. The majority of implementation frameworks expects a polymorph result. Typesafety is a general requirement from a technology independent view. An endpoint, that returns in one case a Submodel, in the next a Reference or a simple, idShort-Name based map, has as return type "Object"/"Any" - a clear anti-pattern in most environments.

An URL Path like /shells/<id>/submodels/<id>/submodel/metadata or /shells/<id>/submodels/<id>/submodel/reference result in very much clearer interfaces, that can be implemented straight in most technologies - with typesafety. An interfaces specification, that can't be expressed in RDF / swagger, most probably doesn't follow best practices guides.

How?

Switch to explicit endpoints, that accept/produce structures, that can be documents in rdf / swagger.

This issue has been raised as IDTA_Repo_4.

[sebbader-sap]

OData for instance promotes:

• /shells/.../submodels/.../submodel/$metadata (https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_MetadataDocumentRequest note that the meaning of OData metadata is different to Content=metadata)
• /shells/.../submodels/.../submodel/$value (https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358940)

[noheton]

I wholeheartedly agree on: "The strategy of modifying result structures via query parameters results in bad implementations." If we want to keep the current API structure regarding modifiers - maybe, we are approaching again on Polymorphism / Discriminator. see https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/ Still, I think this would keep (and encourage) this this bad practice.

From a technical perspective I understand the OData approach as predefined (read standardized) general endpoints for different "response modifications".

Overall, I would rather be in favor of an extensive redesign/refactoring (of the afflicted endpoints) than further building on a fragile (=non-type-safe) solution.

[sebbader-sap]

I try a new approach with a better terminology (Service-Specification vs. API vs. API Operation) and relying on media types instead of Serialisation Parameters: https://app.swaggerhub.com/apis/sebbader/AssetAdministrationShell-ServiceSpecification/V3.0 @noheton @aorzelskiGH @danielporta please have a look before next Tuesday.

[noheton]

Thanks for your experiment.

In my opinion a swagger file cannot be a service-specification, at least I would consider this definition misleading:

Quoting from OAS 3 Spec^1:

OpenAPI Document A self-contained or composite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one paths field, a components field or a webhooks field. An OpenAPI document uses and conforms to the OpenAPI Specification.

I will try to put down my personal understanding of these elements just to find out where our opinions diverge:

API Operation:

• (in AAS context, Part 2): Protocol-agnostic Definition of operations on/with AAS
• (mapped to the REST API "implementation") definition of operations within an API

API:

• the collection of operations in a defined context
• (w.r.t. REST) this is in my opinion the swagger file (see also OAS spec)

Service specification:

• this is not a structural element like an OpenAPISpec rather than a content-driven element which is/should be represented through models in OpenApi
• e.g. we could have a defined endpoint like /service-specification and an accompanying schema for a "Service-Specification-Model"
• this model would encapsulate all necessary information to infer the capabilities and supported interactions (i.e. which API Operations are "implemented") with the server. By the way for me: "service-specification" is synonymous for "profile".
• The following list are examples (non-exhaustive) for contained information in a "service-specification":
  • type of service (e.g. Registry, AASServer, SubmodelHost, a combination)
  • supported model-versions
  • supported operations (aggregated in profiles, or individual operation list)
  • maybe: information on the service provider
  • (to be extended)

Sidenote: Is this the right issue for this topic?

[sebbader-sap]

Hi @noheton,

there are a few things coming together now.

1. The aspect I wanted to highlight, which is in scope of this issue, are the different content-types in https://app.swaggerhub.com/apis/sebbader/AssetAdministrationShell-ServiceSpecification/V3.0#/Asset%20Administration%20Shell%20API/GetAssetAdministrationShell I am proposing yet another alternative for the type-safety problem: Currently: GET https://example.org/aas?content?meta

Proposal 1: GET https://example.org/aas/$meta

Proposal 2 (in the new swagger file):

GET https://example.org/aas

Content-Type: application/json;content=meta

[sebbader-sap]

2. The terminology from OpenApi vs. the Part 2 wording:

API Operation: (in AAS context, Part 2): Protocol-agnostic Definition of operations on/with AAS

No, I see an API and API Operation as protocol-specific. Interface or Interface Operation present the protocol-agnostic part.

Is an OpenApi file the right document to define a Service-Specification? Not sure, but I see several advantages:

1. I want to see it as a structural element in the form of: You want to implement a Repository Service? Great, then implement all APIs of the Repository Service-Specification OpenApi file.
2. You want only a subset of possible Repository functions? Great, then implement all APIs of the Repository Service-Specification Basic-Profile OpenApi file.
3. One API can then be defined by all API Operations which share the same tag (Asset Administration Shell API in the linked file).

The following list are examples (non-exhaustive) for contained information in a "service-specification": type of service (e.g. Registry, AASServer, SubmodelHost, a combination) supported model-versions supported operations (aggregated in profiles, or individual operation list) maybe: information on the service provider (to be extended)

I think I have a different opinion but I am not sure how to express it. Let's talk about it next Tuesday. I think we are not too far away from each other...

[sebbader-sap]

Sidenote: Is this the right issue for this topic?

Not really, or? At least not for the second topic :-). But now we have a vivid offline discussion, so let's just keep it here. The repo is still private, so let's make use of it.

[noheton]

Is an OpenApi file the right document to define a Service-Specification? Not sure, but I see several advantages:

1. I want to see it as a structural element in the form of: You want to implement a Repository Service? Great, then implement all APIs of the Repository Service-Specification OpenApi file.
2. You want only a subset of possible Repository functions? Great, then implement all APIs of the Repository Service-Specification Basic-Profile OpenApi file.
3. One API can then be defined by all API Operations which share the same tag (Asset Administration Shell API in the linked file).

I can see value in this approach (big fan of code generation :) ) - great boilerplate and very useful tool for quickly getting started implementing services, but i don't see a "normative" aspect there.

Another question i am currently asking myself: if someone has a generic AAS-Server REST-client (which would usually be not "service specification aware") how should the server respond if the client tries to call a not-implemented method? I think a specific error should be thrown than a HTTP Status code like 404/405.

[noheton]

Quick idea: Using one OpenApi specification, we could annotate operations with Tags. This would enable consistency and easier maintenance when we define additional endpoints.

[danielporta]

Sticking to the inital topic, I definitely prefer proposal 1. GET https://example.org/aas/$meta

[sebbader-sap]

Additional remark from Basyx:   /shells/_metadata /shells/_reference /shells/{aasIdentifier}/submodels/{submodelIdentifier}/_metadata /shells/{aasIdentifier}/submodels/{submodelIdentifier}/_reference

Which is permitted by https://www.rfc-editor.org/rfc/rfc1738 :

httpurl        = "http://" hostport [ "/" hpath [ "?" search ]] 
hpath          = hsegment *[ "/" hsegment ] 
hsegment       = *[ uchar | ";" | ":" | "@" | "&" | "=" ]
uchar          = unreserved | escape
unreserved     = alpha | digit | safe | extra 
safe           = "$" | "-" | "_" | "." | "+"

RFC 1738: Uniform Resource Locators (URL)

[sebbader-sap]

Continuing with Proposal 1 (the one with .../$metadata paths):

Repository_Service-Specification shows how imagine this approach. Again, a lot of things are mixed, so be aware that:

• PATCH is in there
• Status codes have been extended
• a number of bug fixes
• and of course that the Content query parameter now is a URI path

There is also a first attempt for a profile: Repository-BasicProfile is more or less the Repository_Service-Specification minus Pagination minus Levels minus Content suffix paths

[sebbader-sap]

Same story for the AAS API:

• The BasicProfile presents the absolut minimum to read from an hosted AAS.
• The minimal Profile with WRITE capabilities has also no pagination, Content etc.

And the last is the Submodel API, same pattern as for the AAS API.

[sebbader-sap]

Solution ready with the new ServiceSpecification concept and the respective OpenAPI files.