Guide for Extensions

3 Implementation of Testbed to FIESTA-IoT annotators

3.1 Annotator as a Service

Besides the option of designing and developing the whole annotator module on your own and deploying it at the tested level, we have developed APIs to ease the creation of annotations. These are the annotator-as-a-service APIs. Using the annotator-as-a-service APIs you can pass your legacy data in a defined way to the service. The service will return the semantically annotated FIESTA-IoT Ontology compliant annotations.

In a nutshell, you can generate annotated documents just by sending simple JSON objects to the corresponding endpoints that are resumed in following tables. However, note that the nature of these web services is to provide a generic way to annotate resources, so providing complex descriptions will not be appropriate through this approach. It is understood that for complex cases, you will have to carry out the annotator on your own.

Testbed description generation through the annotator service:

https://platform.fiesta-iot.eu/annotator/api/testbed

Method

Description

Request Body (example)

POST

Service to generate a semantically annotated testbed document (with or without subjacent resources)

{

  "id": <Testbed IRI (string)>,

  "devices": [

    {

      "id": <Device 1 unique ID (string)>,

      "location": {

        "lat": <Latitude (double)>,

        "lon": <Longitude (double)>

      },

      "sensing_devices": [

        {

          "id": <Device 1 Sensor 1 unique ID (string)>,

          "qk": <m3-lite’s QuantityKind (string)>,

          "uom": <m3-lite’s Unit (string)>

        },

        {

          "id": <Device 1 Sensor 2 unique ID (string)>,

          "qk": <m3-lite’s QuantityKind (string)>,

          "uom": <m3-lite’s Unit (string)>        }

      ]

    },

    {

      "id": <Device 2 Sensor 1 unique ID (string)>,

      "location": {

        "lat": <Latitude (double)>,

        "lon": <Longitude (double)>

      },

      "type": "AirThermometer",

      "qk": "TemperatureAmbient",

      "uom": "DegreeCelsius"

    }

  ]

}

Resource description generation through the annotator service:

https://platform.fiesta-iot.eu/utils/annotator/device

Method

Description

Request Body (example)

POST

Service to generate a semantically annotated resource document 

{

  "id": <Device i unique ID (string)>,

  "location": {

    "lat": <Latitude (double)>,

    "lon": <Longitude (double)>

  },

  "sensing_devices": [

    {

      "id": <Device i Sensor 1 unique ID (string)>,

      "qk": <m3-lite’s QuantityKind (string)>,

      "uom": <m3-lite’s Unit (string)>

    },

    {

      "id": <Device i Sensor 2 unique ID (string)>,

      "qk": <m3-lite’s QuantityKind (string)>,

      "uom": <m3-lite’s Unit (string)>

    }

  ]

}

Observation description generation through the annotator service:

https://platform.fiesta-iot.eu/annotator/api/observation

Method

Description

Request Body (example)

POST

Service to generate a semantically annotated observation document 

{

"observed_by": <Sensor unique ID (string)>,

  "location": {

    "lat": <Latitude (double)>,

    "lon": <Longitude (double)>

  },

  "quantity_kind": "TemperatureAmbient",

  "value": <Value>,

  "format": <Type (integer, float, etc.)>,

  "unit": <m3-lite’s Unit (string)>,

  "timestamp": <Date>

}

As for the response of these methods, the iot-registry module returns appropriate message along with the status code in the same formats as the ones enumerated in Section 1.5.