General Services, Interfaces and Interface Operations This document uses the Industrie 4.0 Service Model illustrated in Figure 1 for a uniform understanding and naming. It basically distinguishes between associated concepts on several levels (from left to right): technology-neutral level: concepts that are independent of selected technologies; technology-specific level: concepts that are instantiated for a given technology and/or architectural style (e.g. HTTP/REST, OPC UA, MQTT); implementation level: concepts that are related to an implementation architecture that comprises one or more technologies (e.g. C#, C++, Java, Python); runtime level: concepts that are related to identifiable components in an operational Industry 4.0 system. This document deals with the concepts of the technology-neutral and technology-specific level. However, to avoid terminological and conceptual misunderstandings, the whole Industrie 4.0 Service Model is provided here. The technology-neutral level comprises the following concepts: Service: a service describes a demarcated scope of functionality (including its informational and non-functional aspects), which is offered by an entity or organization via interfaces. Interface: this is the most important concept as it is understood to be the unit of reusability across services and the unit of standardization when mapped to application programming interfaces (API) in the technology-specific level. One interface may be mapped to several APIs depending on the technology and architectural style used, e.g. HTTP/REST or OPC UA, whereby these API mappings also need to be standardized for the sake of interoperability. Interface-Operation: interface operations define interaction patterns via the specified interface. The technology-specific level comprises the following concepts: Service Specification: specification of a service according to the notation, architectural style, and constraints of a selected technology. Among others, it comprises and refers to the list of APIs that forms this service specification. These may be I4.0-defined standard APIs but also other, proprietary APIs. Note: such a technology-specific service specification may be but does not have to be derived from the “service” described in the technology-neutral form. It is up to the system architect and service engineer to tailor the technology-specific service according to the needs of the use cases. API: specification of the set of operations and events that forms an API in a selected technology. It is derived from the interface description on the technology-neutral level. Hence, if there are several selected technologies, one interface may be mapped to several APIs. API-Operation: specification of the operations (procedures) that may be called through an API. It is derived from the interface operation description on the technology-neutral level. When selecting technologies, one interface operation may be mapped to several API-operations; several interface operations may also be mapped to the same API-operation. The implementation level comprises the following concepts: Service-Implementation: service realized in a selected implementation language following the specification in the Service Specification description on the technology-specific level. API-Implementation: set of operations realized in a selected implementation language following the specification in the API description on the technology-specific level. API-Operation-Implementation: concrete realization of an operation in a selected implementation language following the specification in the API-Operation description on the technology-specific level. The runtime level comprises the following concepts: Service-Instance: instance of a Service-Implementation including its API-Instances for communication. Additionally, it has an identifier to be identifiable within a given context. API-Instance: instance of an API-Implementation which has an endpoint to get the information about this instance and the related operations. API-Operation-Instance: instance of an API-Operation-Implementation which has an endpoint to get invoked. Figure 1. Services, Interfaces & APIs and Operations One important message from the Industrie 4.0 Service Model is that it is the level of the interface (mapped to technology-specific APIs) that provides the unit of reusability, is the foundation for interoperable services, and provides the reference unit for compliance statements. Therefore, this document defines the interfaces and operations which are needed for interaction regarding the elements of the Asset Administration Shell metamodel starting with Clause 5. Design Principles The operations of the interfaces follow a resource-oriented approach which is close to general REST principles but not as strict in every situation. The approach consists of the three main agreements: Stateless: the API is stateless. Each operation is independent. The server is always consistent after each operation. Resources (nouns): each resource is a clearly defined noun. This means that it has a specific name and its relation to other nouns is defined. The nouns and the relationships between them are taken from the list of referable objects of “Specification of the Asset Administration Shell Part 1” and their relationships. Metamodel Specification Details gives an additional list of resources. Methods (verbs): a small set of standard REST methods (GET, POST, PUT, DELETE) is used to describe the semantic of the most common operations. There are only a few exceptions for situations where the standard methods do not fit (e.g. GETALL, SET, INVOKE). The methods are: GET: a GET returns a single resource based on the resource identifier which is the identifier [1] for identifiables and the idShortPath for referables. GETALL: returns a list of resources based on optionally available parameters such as filters. POST: creates a new resource. The identifier of the resource is part of the resource description. This is necessary because the id of identifiables is globally unique and should be the identifier for the object in every system. This implies that the creation of an identifiable is idempotent. There shall never be more than one identifiable with the same ID in one system. For example, trying to post the same AAS object twice will not create two AAS resources. PUT: replaces an existing resource. PATCH: updates an existing resource. The content to be replaced will be defined by the given SerializationModifiers, e.g. content=value provides the ValueOnly-serialization to update all values in the existing resource. The structure of the existing resource on the server and of the content given by the PATCH must be the same. Note: values remain unchanged with content=metadata. DELETE: deletes a resource based on a given identifier. SET: sets the value of an object, e.g. the value of a Property. INVOKE: invokes an operation at a specified path. Note: these methods are intended for the naming of interfaces as described in Figure 1. They shall not be interpreted as new protocol methods, e.g. on HTTP level. Naming rules for operations: The following rules shall apply for the operation names in Asset Administration Shell Interface, Submodel Interface, Shell Repository Interface, Submodel Repository Interface, Concept Description Repository Interface: <Interface Operation> ::= <Method Verb><Model Element Name>[<Modifier>]["By"<By-Qualifier>] <Method Verb> ::= "Get" | "GetAll" | "Put" | "PutBulk" | "Post" | "PostBulk" | "Patch" | "Delete" | "DeleteBulk" | "SetInvoke" | "InvokeAsync" | "SearchAll" <Model Element Name> ::= "AssetAdministrationShell"["s"] | "AssetAdministrationShellDescriptor"["s"] | "SubmodelReference"["s"] | "AssetInformation" | "Submodel"["s"] | "SubmodelDescriptor"["s"] | "SubmodelElement"["s"] | "ConceptDescription"["s"] <Modifier> ::= "Value" | "IdShortPath" | "Reference" <By-Qualifier ::= |"Id" | "SemanticId" | "ParentPathAndSemanticId" | "Path" | "AssetId" | "IdShort" | "IsCaseOf" | "DataSpecificationReference" Examples: GetSubmodel has method verb “Get” and model element name “Submodel”. GetAllSubmodelElementsByPath has method verb “GetAll” and model element name “SubmodelElements” plus a by-qualifier “Path”. Semantic References for Operations The operations of this document need unique identifiers to reach a common understanding and allow all involved parties to reference the same things. These identifiers need to be globally unique and understandable by the community and implementing systems. Furthermore, the identifiers need to support a versioning scheme for future updates and extensions of the metamodel. The identifiers defined in this document are reused in related resources, for instance REST API operations or in self-descriptions of implementing services. Internationalized Resource Identifiers (IRIs), Uniform Resource Identifiers (URIs) [5] in particular, and the requirements of DIN SPEC 91406 [6], serve as the basic format. Further design decisions include ‘https’ as the URI scheme, and the controlled domain name ‘admin-shell.io’ as the chosen authority. Both decisions guarantee the interoperability of the identifiers and their durability, since URIs are generally well-known and proven, while the domain is controlled and served through the Plattform Industrie 4.0. All identifiers included in the ‘admin-shell.io’ domain are described in a lightweight catalogue in the form of Markdown documents; they are continuously maintained and updated [https://github.com/admin-shell-io/id]. The catalogue itself is structured in several sub-namespaces specified by the first path parameter. All URIs of this document reflect entities of the core metamodel, which are contained in the sub-namespace identified with the ‘/aas/API’ path. The described identifiers appear mainly in the semanticId field of every class and operation. They are required since the class name is not necessarily constant over time. The respective semanticIds, however, guarantee the unique and certain relation between a reference and the referenced class or operation. The URIs are constructed as follows (compare to Clause Semantic Identifiers for Metamodel and Data Specifications in Part 1 [1]). Note 1: version information is explicitly included in each identifier. Note 2: even though the usage of the ‘https’ scheme might indicate URLs, all identifiers are regarded as URI look-ups; dereferencing them cannot be expected. The following grammar is used to create valid identifiers: <Identifier> ::= <Namespace>"/aas/API/"<OperationName>"/"<Version> <Namespace> ::= "https://admin-shell.io <OperationName> ::= {<Character>}+ <Version> ::= {<Digit>}+"/"{<Digit>}+["/"{<Character>}+] <Digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" <Character> ::= an unreserved character permitted by DIN SPEC 91406 ? ::= zero or one + ::= one or more Examples for valid identifiers: https://admin-shell.io/aas/API/GetSubmodel/1/23 https://admin-shell.io/aas/API/GetAllSubmodelElements/1/0/RC03 https://admin-shell.io/aas/API/GetAllSubmodelElements/3/0 Examples for invalid identifiers: http://admin-shell.io/API/GetSubmodel/1/0 The scheme is different to ‘https’, and the ‘aas’ path segment is missing https://admin-shell.io/aas/API/GetSubmodel Version information is missing https://admin-shell.io/aas/API/GetSubmodel/1/0#0173-%20ABC#001 The URI includes DIN SPEC 91406-reserved (#) and impermissible (%) characters References and Keys The concept of references is introduced in Part 1 of the series “Specification of the Asset Administration Shell” [1]. When defining interfaces, a distinction is made between relative references and absolute references. Absolute references require a global unique id as starting point of the reference to be resolvable. In this case the type “Reference” is used. Relative references do not start with a global unique id. Instead, it is assumed that the context is given and unique. In this case, the key list only contains keys with Key/type that references a non-identifiable referable (e.g. a Property, a Range, a RelationshipElement, etc.). Relation of Interfaces The following chapters define several interfaces, which work together as a system and support different deployment scenarios. There are three major components of the overall system: Repositories store the data of Asset Administration Shells, Submodels, and Concept Descriptions, Registries are “directories” which store AAS-IDs and Submodel-IDs together with the related endpoints (typically a URL-path into a repository or to a single AAS/Submodel), discovery (servers) supports a fast search and only store copies of essential information, i.e. key value pairs to find IDs by other IDs. Figure 2 shows a typical sequence. Discovery finds the AAS-ID for a given Asset-ID. A Registry provides the endpoint for a given AAS-ID. Such an endpoint for an AAS and the related Submodel-IDs make the submodels with their submodelElements accessible. Figure 2. Retrieval of Asset-related Information by AAS and Submodels The Asset Administration Shell model is an asset-oriented model. An Asset-ID may be retrieved e.g. by a QRCODE on the asset, by an RFID for the asset, from the firmware of the asset or from an asset database. IEC 61406 (formerly DIN SPEC 91406) defines the format of such Asset-IDs. The “Administration Shell Basic Discovery Interface” may be used with an Asset-ID to get the related AAS-IDs (“GetAllAssetAdministrationShellIdsByAssetLink”). The “Asset Administration Shell Registry Interface” may be used with an AAS-ID to retrieve the related descriptor for an AAS (“GetAssetAdministrationShellDescriptorById”). The retrieved AAS Descriptor includes the endpoint for the “Asset Administration Shell Interface”. The “Asset Administration Shell Interface” makes the information about the AAS itself and the references to the related submodels available. The related submodels of an AAS are retrieved by “GetAllSubmodelReferences”. Such a reference includes the SM-ID of a related submodel. Similarly to the AAS above, the “Submodel Registry Interface” may be used to retrieve the related descriptor for a submodel (“GetSubmodelDescriptorById”) with a specific SM-ID. The retrieved Submodel Descriptor includes the endpoint for the “Submodel Interface”. The “Submodel Interface” makes the information about the submodel itself and all its included submodel elements available. Asset Administration Shells and submodels may be deployed on different endpoints in different ways. One example is the deployment of an AAS on a device. In this case, the AAS might be fixed and might not be changed or deleted. In a cloud scenario, a single AAS may also be deployed as a single container (e.g. docker container). Another example is the deployment of many Asset Administration Shells in an AAS Repository. In this case, the “Asset Administration Shell Repository Interface” may allow to create and manage multiple AAS in the repository. The separate interfaces of the HTTP/REST API allow many ways to support different deployments. For an AAS repository, the combination “Asset Administration Shell Repository Interface”, “Asset Administration Shell Interface”, “Submodel Interface”, “Serialization Interface”, and “Self-Description Interface” is proposed. This will result in the following HTTP/REST paths as described in a combined OpenAPI file (For easier reading only the standard paths are shown in the following: $metadata, $value, $reference and $path parameter paths are additionally contained in the OpenAPI file.: /shells /shells/{aas-identifier} /shells/{aas-identifier}/asset-information /shells/{aas-identifier}/asset-information/thumbnail /shells/{aas-identifier}/submodel-refs /shells/{aas-identifier}/submodel-refs/{submodel-identifier} /shells/{aas-identifier}/submodels/{submodel-identifier} /shells/{aas-identifier}/submodels/{submodel-identifier}/submodel-elements /shells/{aas-identifier}/submodels/{submodel-identifier}/submodel-elements/{idShortPath} /shells/{aas-identifier}/submodels/{submodel-identifier}/submodel-elements/{idShortPath}/attachment /shells/{aas-identifier}/submodels/{submodel-identifier}/submodel-elements/{idShortPath}/invoke /shells/{aas-identifier}/submodels/{submodel-identifier}/submodel-elements/{idShortPath}/invoke-async /shells/{aas-identifier}/submodels/{submodel-identifier}/submodel-elements/{idShortPath}/operation-status/{handleId} /shells/{aas-identifier}/submodels/{submodel-identifier}/submodel-elements/{idShortPath}/operation-results/{handleId} /serialization /description If the repository also supports AASX Packages, it shall be extended by additionally supporting a “AASX File Server” Profile [Related OpenAPI file: https://app.swaggerhub.com/apis/Plattform_i40/AasxFileServerServiceSpecification/V3.1_SSP-001]. The example of a device or container containing one AAS with its related submodels will result in the following HTTP/REST paths as described in the related OpenAPI file (https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellServiceSpecification/V3.1_SSP-001)2: /aas /aas/asset-information /aas/asset-information/thumbnail /aas/submodel-refs /aas/submodel-refs/{submodel-identifier} /aas/submodels/{submodel-identifier} /aas/submodels/{submodel-identifier}/submodel-elements /aas/submodels/{submodel-identifier}/submodel-elements/{idShortPath} /aas/submodels/{submodel-identifier}/submodel-elements/{idShortPath}/attachment /aas/submodels/{submodel-identifier}/submodel-elements/{idShortPath}/invoke /aas/submodels/{submodel-identifier}/submodel-elements/{idShortPath}/invoke-async /aas/submodels/{submodel-identifier}/submodel-elements/{idShortPath}/operation-status/{handleId} /aas/submodels/{submodel-identifier}/submodel-elements/{idShortPath}/operation-results/{handleId} /serialization /description Note: identifiers are base64url-encoded in the API, i.e. {aas-identifier} and {submodel-identifier}. The {idShortPath} is URL-encoded in the API.