search

admin-shell-io / questions-and-answers

This repository aims for providing answers to often asked questions in the context of the Asset Administration Shell.
https://admin-shell-io.github.io/questions-and-answers/
Creative Commons Attribution 4.0 International
24 stars 6 forks source link

How to write a valid endpoint/valid endpoints into the registry using the Asset Administration Shell Registry Service? #89

Open BirgitBoss opened 1 year ago

BirgitBoss commented 1 year ago

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?

BirgitBoss commented 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" 

        } 

    ] 

}
BirgitBoss commented 1 year ago

@sebbader-sap Could you please discuss this in TF AAS API?

A next question would be how to combine this with EDC endpoints.

BirgitBoss commented 1 year ago

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" 

        }
sebbader-sap commented 1 year ago

Preparing the solution in this branch: https://github.com/admin-shell-io/questions-and-answers/tree/89_best-practice-descriptor-endpoints

StenGruener commented 1 year ago

@sebbader-sap @BirgitBoss should we separate the example value discussion from the API definition?

sebbader-sap commented 1 year ago

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.

sebbader-sap commented 1 year ago

I updated my proposal. Please give me feedback on the content. @danielporta you wanted to add something too, correct?

danielporta commented 1 year ago

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 hrefvalue 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..)

sebbader-sap commented 1 year ago

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

StenGruener commented 1 year ago

@sebbader-sap could you present this one next week monday?

sebbader-sap commented 1 year ago

Hardly, have a conflicting call. But I think one or two people from our discussion will join...

StenGruener commented 1 year ago

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"
   ]
}