http_endpoint.md

HTTP Endpoint

The HTTP Endpoint allows accessing data and execute operations within the FA³ST Service via REST-API. The HTTP Endpoint is based on the document Details of the Asset Administration Shell - Part 2, Interoperability at Runtime – Exchanging Information via Application Programming Interfaces (Version 1.0RC02)' , November 2021 and the OpenAPI documentation DotAAS Part 2 | HTTP/REST | Entire Interface Collection, Apr, 26th 2022

For detailed information on the REST API see DotAAS Part 2 | HTTP/REST | Entire Interface Collection, Apr, 26th 2022

In order to use the HTTP Endpoint the configuration settings require to include an HTTP Endpoint configuration, like the one below:

{
	"endpoints": [
		{
			"@class": "de.fraunhofer.iosb.ilt.faaast.service.endpoint.http.HttpEndpoint",
			"port": 8080
		}
	]
}

API

Supported API calls

• Asset Administration Shell Repository Interface

  • /shells
  • /shells/{aasIdentifier}

• Asset Administration Shell Interface

  • /shells/{aasIdentifier}/aas
  • /shells/{aasIdentifier}/aas/asset-information
  • /shells/{aasIdentifier}/aas/submodels
  • /shells/{aasIdentifier}/aas/submodels/{submodelIdentifier}

• Submodel Repository Interface

  • /submodels
  • /submodels/{submodelIdentifier}

• Submodel Interface

  • /submodels/{submodelIdentifier}/submodel
  • /submodels/{submodelIdentifier}/submodel/submodel-elements
  • /submodels/{submodelIdentifier}/submodel/submodel-elements/{idShortPath}
  • /submodels/{submodelIdentifier}/submodel/submodel-elements/{idShortPath}/invoke
  • /submodels/{submodelIdentifier}/submodel/submodel-elements/{idShortPath}/operation-results/{handle-Id}

• Submodel Interface (combined with Asset Administration Shell Interface)

  • /shells/{aasIdentifier}/aas/submodels/{submodelIdentifier}/submodel
  • /shells/{aasIdentifier}/aas/submodels/{submodelIdentifier}/submodel/submodel-elements
  • /shells/{aasIdentifier}/aas/submodels/{submodelIdentifier}/submodel/submodel-elements/{idShortPath} , ,
  • /shells/{aasIdentifier}/aas/submodels/{submodelIdentifier}/submodel/submodel-elements/{idShortPath}/invoke
  • /shells/{aasIdentifier}/aas/submodels/{submodelIdentifier}/submodel/submodel-elements/{idShortPath}/operation-results/{handle-Id}

• Concept Description Repository Interface

  • /concept-descriptions
  • /concept-descriptions/{cdIdentifier}

• Asset Administration Shell Basic Discovery

  • /lookup/shells
  • /lookup/shells/{aasIdentifier}

• Asset Administration Shell Serialization Interface

  • /serialization

Optional query parameters

• level=deep|core
• content=normal|value|path
• extent=WithoutBLOBValue/WithBLOBValue
• InvokeOperation supports async=true/false

They are added to the URL as regular query params

http://url:port?level=deep&content=value

FA³ST Service currently supports only content=value and content=normal

Unsupported API calls

• Asset Administration Shell Registry Interface (out-of-scope)
• Submodel Registry Interface (out-of-scope)
• AASX File Server Interface (probably supported in future)
  • /packages
  • /packages/{packageId}

Example

Sample HTTP Call for Operation GetSubmodelElementByPath using the parameters

• submodelIdentifier: https://acplt.org/Test_Submodel (must be base64URL-encoded)
• idShortPath: ExampleRelationshipElement (must be URL-encoded)

using the query-parameters level=deep and content=normal.

To avoid problems with IRIs in URLs the identifiers shall be BASE64-URL-encoded before using them as parameters in the HTTP APIs. IdshortPaths are URL-encoded to handle including square brackets.

http://localhost:8080/submodels/aHR0cHM6Ly9hY3BsdC5vcmcvVGVzdF9TdWJtb2RlbA==/submodel/submodel-elements/ExampleRelationshipElement?level=deep&content=normal