Implement your Aspect Model as an API

An aspect implementation is the service that will provide actual data which corresponds to a given Aspect Model. The endpoint of the aspect implementation is what will be registered with a digital twin in the Digital Twin Registry. There are multiple aspect endpoint types for which aspects can be registered, in particular they are based on either HTTP(S) or MQTT.
In this short guide, we will focus on an aspect implementation based on HTTP.

In the previous section Create a new Aspect Model, we have developed a simple Aspect Model that describes vibration data. In order to implement an aspect for this model, the easiest way to start is by generating a sample JSON payload for this Aspect Model, i.e., a JSON snippet that structurally looks like it could be the response from this aspect.

The open source tooling for Aspect Models provides easy ways to generate such an example payload, either programmatically from a Java program or using the Semantic Aspect Meta Model (SAMM) command line interface. See SAMM CLI.

Using the CLI

In this section we will use the Semantic Aspect Meta Model (SAMM) Command Line Interface.

  1. Download the latest version of the samm-cli.jar file from its release page.

  2. Make sure your Aspect Model is located in a directory structure, that corresponds to its namespace.
    For example, if the model’s namespace is urn:samm:com.mycompany.myproduct:1.0.0# then the model file must be located in the directory structure com.mycompany.myproduct/1.0.0/ModelFile.ttl.
    If you have used the Aspect Model Editor to create the model, you won’t have to do anything as this will already be the case, see file directory structure in the Aspect Model Editor documentation.

  3. Use a command shell, cd into the directory with your Aspect Model, and run the command:

    java -jar samm-cli-2.3.1.jar aspect Vibration.ttl to json

    This will generate a piece of JSON code that shows you how a corresponding JSON response should be structured:

    {
      "vibration" : 3.3635022E38
    }

You now have several options:

  1. Use your favorite language and framework to implement a regular web service from scratch which responds to HTTP GET requests with a payload of this structure.

  2. Alternatively, leverage the samm-cli once more and use it to generate an OpenAPI specification for this endpoint.
    Details on how this is done can be found in the corresponding documentation.
    You will receive a .yaml or .json file that describes the payload of your aspect endpoint. The components in the API description will reflect the structure of the elements in the Aspect Model:

    components:
        urn_bamm_com.bosch.nexeed.digitaltwin_1.0.0_VibrationMeasurement:
          type: number
        Vibration:
          type: object
          properties:
            vibration:
              $ref: '#/components/schemas/urn_bamm_com.bosch.nexeed.digitaltwin_1.0.0_VibrationMeasurement'
          required:
          - vibration

    Note that this API description retains information on the structure of the data, but due to the differences between an API description and a semantic model, the API description will not contain the semantic information from the original Aspect Model.

    You can then use a tool such as the OpenAPI Generator to generate a basic server implementation for the aspect.

  3. You can also use the samm-cli with its aspect to java subcommand to generate Java classes that represent the domain data model of the aspect and use those in the aspect implementation’s code base — if it is built using the Java language.

After the implementation of the aspect, you need to deploy it to a hosting provider of your choice and register its endpoint to a digital twin with the Digital Twin Registry.