Open BirgitBoss opened 1 year ago
There are two main alternatives how to do it:
Alternative 1) here the data consumer needs to parse the href and add the needed parameter itself, i.e. step 1) get http AAS endpoint href: http://<...>/submodel step 2) add suffix: http://<...>/submodel/$value step 3) call endpoint
{
"protocolInformation": {
href: http://<...>/submodel
endpointProtocol: HTTP,
subprotocol: AAS
},
"interface": "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-003"
},
Alternative 2) here the data consumer needs to find the correct subprotocol step 1) look for http endpoint with subprotocol "AAS-VALUE" step 2) get endpoint href http://<...>/submodel/$value step 3) call endpoint
{
"endpoints": [
{
"protocolInformation": {
href: http://<...>/submodel
endpointProtocol: HTTP,
subprotocol: AAS-NORMAL
},
"interface": "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-003"
},
{
"protocolInformation": {
href: http://<...>/submodel/$value
endpointProtocol: HTTP,
subprotocol: AAS-VALUE
},
"interface": "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-003"
}
{
"protocolInformation": {
href: http://<...>/submodel/$metadata
endpointProtocol: HTTP,
subprotocol: AAS-METADTA
},
"interface": "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-001"
}
]
}
@sebbader-sap Could you please discuss this in TF AAS API?
A next question would be how to combine this with EDC endpoints.
Example for endpoint with protocol version:
the protocol endpoint version refers to the version of the IDS specification being the basis... Where to find the version of the AAS specification?
{
"interface": "
https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-003
",
"protocolInformation": {
"href": "https://edc.data.plane/shells/{aasIdentifier}/submodels/{submodelIdentifier}/submodel",
"endpointProtocol": "http",
"endpointProtocolVersion: "0.1",
"subprotocol": "IDS//AAS/AAS-VALUE",
"subprotocolBody": "asset:prop:assetoffer=9300395e-c0a5-4e88-bc57-a3973fec4c26;idsEndpoint=http://edc.control.plane/", ?????
"subprotocolBodyEncoding": "plain"
}
}
or
{
"interface": "SUBMODEL-1.0",
"protocolInformation": {
"endpointAddress": "https://edc.data.plane/shells/{aasIdentifier}/submodels/{submodelIdentifier}/submodel",
"endpointProtocol": "AAS/IDS",
"endpointProtocolVersion: "0.1",
"subprotocol": "IDS",
"subprotocolBody": "asset:prop:assetoffer=9300395e-c0a5-4e88-bc57-a3973fec4c26;idsEndpoint=http://edc.control.plane/",
"subprotocolBodyEncoding": "plain"
}
}
For AAS without EDC - but then again it is unclear whether this is http or MQTT or ...
{
"protocolInformation": {
href: http://<...>/submodel/$value
endpointProtocol: AAS,
endpointProtocolVersion: "3.0"
subprotocol: AAS-VALUE
},
"interface": "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-003"
}
with version in subprotocol:
{
"protocolInformation": {
href: http://<...>/submodel/$value
endpointProtocol: http,
subprotocol: AAS-VALUE-3.0
},
"interface": "https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-003"
}
Preparing the solution in this branch: https://github.com/admin-shell-io/questions-and-answers/tree/89_best-practice-descriptor-endpoints
@sebbader-sap @BirgitBoss should we separate the example value discussion from the API definition?
Not sure what you mean with API definition... The definition itself comes from Part 2 but we need to find best practices how to use the specified attributes in the different scenarios. Therefore, I think it fits into the Q&As.
I updated my proposal. Please give me feedback on the content. @danielporta you wanted to add something too, correct?
The longer I think about it, the more I get confused with endpointProtocol, subprotocol (camelCase would have been nice btw.) and interface. Trying to sort things out for me, I am still not really happy...
On page 82, interface is defined as {interface-shortName}-{interface-version}
. If we want to use the profile instead, this should be fixed in the document first. However, I would not recommend this:
Let's assume we use the profile as interface value. How will the protocol information looks like? I would assume that (in the case of a registered submodel) the href
value is the endpoint from which I could call GetSubmodel
(/submodel), GenerateSerializationByIds
(/serialization) and also GetDescription
(/description). For a dedicated submodel service this might be ok. But what if that submodel is hosted on a submodel repository? Will we use the profile of the repository as interface value? Derive a profile for the actual submodel? I don't think that will work - and I wonder why: the issue arises most likely because the profiles are more service-specific (submodel service, submodel repo service) and not content-specific. Whereas the registry services are used to register "content" in terms of AASs and submodels. Overall, I propose to stick to the "old" interface definition.
Then, we might have something like this:
"endpoints": [
{
"interface": "SUBMODEL-3.0.1" ,
"protocolInformation": {
"href": "https://<hostname>/path-to-submodel-entrypoint"
"endpointProtocol": "HTTP",
"endpointProtocolVersion: "1.1",
"securityAttributes": [ { "type": "NONE", "key": "NONE", "value": "NONE" } ]
}
}
]
In case of HTTP/REST-based access according to the OpenAPI definitions, endpointProtocol and -version relates for me to the HTTP layer. I don't think anybody really cares about them. And I don't see any use of subprotocol entries.
Now, what is the path-to-submodel-entrypoint
? From a consumer's perspective I would argue that this is the URL from which I can retrieve the whole submodel. Typical patterns look like, /submodel
, /submodels/{submodelIdentifier}
, /shells/{aasIdentifier}/submodels/{submodelIdentifier}
. These patterns may also indicate where to find the description and serialization endpoints if needed. A more intelligent client SDK could use that in order to find out automatically which operations are possible before calling them and prevent running into HTTP errors.
Regarding the serialization endpoint we should probably think about if it makes sense attaching that endpoint to all the AAS and submodels via superpaths or leave it associated with a service.
Regarding the AAS-over-IDS use case I don't see the point. Either the specified href points to one of "our" REST-APIs (e.g. an AAS repo that interfaces with an IDS instance in the back-end; somebody will probably implement that;-) ). Then, see above. Or it points to an (HTTP) endpoint that implements a "custom specification". Then, good luck... or night (sorry, it got later than expected..)
@BirgitBoss and @danielporta please check my proposal. I accidentally made it the longest answer so far so please don't hesitate to split it. However, I think that each of the variants is with being mentioned...
@sebbader-sap could you present this one next week monday?
Hardly, have a conflicting call. But I think one or two people from our discussion will join...
Current state presented by @BirgitBoss, fyi @sebbader-sap
{
"id": "<unique ID of submodel>",
"semanticId": {
"type": "ExternalReference",
"keys": [
{"type": "GlobalReference",
"value": "urn:bamm:io.catenax.material_for_recycling:1.1.0#MaterialForRecycling"}
]
},
"endpoints": [
{
"protocolInformation": {
"href": "https://edc.data.plane/<path>/submodel",
"endpointProtocol": "HTTP",
"endpointProtocolVersion": ["1.1"],
"subprotocol": "IDS",
"subprotocolBody": "<body with information required by subprotocol>",
"subprotocolBodyEncoding": "plain",
"securityAttributes": [
{ "type": "NONE", "key": "NONE", "value": "NONE" }
]
}
"interface": "SUBMODEL-3.0"
}
]
}
{
"profiles": [
"https://admin-shell.io/aas/API/3/0/DiscoveryServiceSpecification/SSP-001",
"https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002"
]
}
Context: AAS Specification V3.0 Part 2 https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API.pdf + Profile AssetAdministrationShellRegistryServiceSpecification/SSP-001 + SubmodelServiceSpecification/SSP-003
The logical parameter Content with its values Value Normal etc. is (in the http serialization) now realized via an operation-suffix, e.g. /submodel/$value, the default Normal is realized as /submodel
Question: How to write a valid endpoint/valid endpoints into the registry using the Asset Administration Shell Registry Service?