---
tags: Ideas, brainstorming, wp2
title: API/app label implementation
---

# Implementazione API/app Label
## Note da una call tra Marco e Michele (18/10/2021)

Siamo partiti da analizzare dello pseudocodice di Luca B:

int main(void) 
{ 
  SIFISContext *s = register_to_the_home(); 
  SIFISDevice *d = lookup_devices(s, DEVICE_KIND("forno"));
  
  SIFISProperty *p = lookup_property(d[0], PROPERTY_KIND("elemento riscaldante"));
  change_property(p[0], 100);
}

Luca dice che, in questo pezzo di codice scritto da un third-party developer, le "API" alle quali sono associate le API label sono quelle scritte in maiuscolo.

Io penso che l'API label debba essere associato alla API `change_property()`.

L'idea dietro alle Label è questa: se un'applicazione può accendere il forno di casa, ovvero, se all'interno del codice dell’applicazione c’è la chiamata alla API `turnOnOven()`, allora l’API label viene incluso tra i label che andranno a formare l’app label.
Questo API label è un oggetto JSON che descrive i vari rischi introdotti dall’esecuzione di tale API.

Nell’esempio di Luca, mi par di capire che un API label sia associato a una proprietà del device e/o al device stesso.
Questo però non mi torna, perché un’app che usa solo la API `turnOffOven()` (spegni forno) secondo me dovrebbe essere etichettata diversamente da un’app che usa solo `turnOnOven()`.
Quest’ultima dovrebbe comprendere il tag “rischio incendio”, mentre la prima, che permette solo di spegnere il forno, no.

Parlando sono venute fuori delle considerazioni interessanti sul `risk_score` associato ai tag.
Prima però un breve riassunto su come sono stati definiti API label e app label in D2.2.

> [name=Luca Barbato]
> Puoi avere ogni sorta di API messa sopra un'altra, per quello che vedo le api FIWARE e WebOfThings sono sul paradigma proprietà-autodescrizione.
> Idealmente possiam guardare le [librerie](https://webthings.io/framework/) disponibili e provare a capire come estenderle per aggiungere le label discusse.
> In generale uno dei problemi è che vorremmo avere la piena analisi statica senza doverla fare.
> Un trucco è usare una API in cui azione, proprietà e descrizione sono tutte unite ma hai il problema non piccolo di avere qualcosa di inflessibile e che esplode di combinazioni.

## Riassunto labels (D2.2)
Per essere chiaro e ricapitolare:
* un API label è formato da uno o più tag, e porta informazione circa i rischi derivanti dall’esecuzione di tale API
* un tag identifica un rischio e, in alcuni casi la sua entità (`risk_score`)
* un tag appartiene a una tra le categorie: safety, privacy, e financial.
* un app label è creato a partire dalla collezione di tutti gli API label associati alle APIs usate all’interno del codice dell’applicazione.

Un esempio di API label per l’API `turnOnOven()` è

{
  "api_name": "turnOnOven",
  "description": "Activates the oven at the last selected temperature.",
  "security_label": {
    "safety": [ {
        "name": "FIRE_HAZARD",
        "description": "The execution may cause fire." 
        }, {
        "name": "POWER_OUTAGE",
        "description": "High instantaneous power. The execution may cause power outage.",
        "risk_score": 0.8
        } ],
    "privacy": [ {
        "name": "LOG_ENERGY_CONSUMPTION",
        "description": "The execution allows the app to register information abou t energy consumption."
        } ],
    "financial": [ {
        "name": "ELECTRIC_ENERGY_CONSUMPTION",
        "description": "The execution enables the device to consume further elect ricity.",
        "risk_score": 0.8
        } ] 
    }
}

In questo esempio, l’API label è costituito da quattro tag. FIRE_HAZARD e POWER_OUTAGE appartengono alla categoria safety, LOG_ENERGY_CONSUMPTION alla categoria privacy e ELECTRIC_ENERGY_CONSUMPTION alla categoria financial.
POWER_OUTAGE e ELECTRIC_ENERGY_CONSUMPTION sono tag che comprendono anche un risk score, un numero tra 0 e 1 che indica la gravità del rischio.

## Idea per l'assegnazione del risk score
Nel D2.2 non abbiamo ancora indicato come viene assegnato il risk score, cioè se è un “esperto” che lo assegna staticamente all’API label, o se può variare in base a qualche meccanismo “intelligente”.
Per un determinato API label, il valore del risk score dipende sicuramente dal tipo di device (DEVICE_KIND, per riprendere la terminologia di Luca).
Vale a dire che l’API label di `turnOnOven()` e di `turnOnLight()`, che comprendono entrambi il tag ELECTRIC_ENERGY_CONSUMPTION, avranno due valori di risk score diversi. Accendere il forno consuma più energia che accendere una lampadina, quindi il suo risk score sarà più alto.
Questa sarebbe la modalità esperto, che non considera tuttavia le proprietà del device che si va ad accendere.

Supponiamo di avere due forni A e B. Per A, la massima temperatura è 500°C, mentre B arriva al massimo a 200°C. I loro consumi, quando accesi alla massima temperatura, sono rispettivamente 2000W e 800W.
Immaginiamo che la API `turnOnOven()` prenda in ingresso la percentuale `perc` di potenza (o di temperatura) alla quale si vuole accendere il forno, e un riferimento al device che si vuole accendere.
Quindi, `turnOnOven(A, 100)` accende il forno A a 500°C.
Se nel codice troviamo questa chiamata, il meccanismo intelligente dovrebbe ricavare la massima temperatura/potenza dalle proprietà del forno A (`max_temp`), e calcolare `perc*max_temp` per capire la temperatura/potenza a cui verrà effettivamente acceso il forno. Da questo dato, si potrebbe calcolare e impostare il `risk_score` per il tag ELECTRIC_ENERGY_CONSUMPTION in base a una qualche mappatura decisa da noi.
Esempio di mappatura:

| risk score | effective temp (°C) |
| ---------- | ------------------- |
| 1 | 1000+ |
| 0.9 | 900-999 |
| ... | ... |
| 0.1 | 100-199 |
| 0 | 0-99 |

Con questa mappatura la chiamata
`turnOnOven(A, 80)` avrà `risk_score=0.4`
mentre la chiamata
`turnOnOven(B, 80)` avrà `risk_score=0.1`

Qui si nota bene che due chiamate alla stessa API producono label diversi (in termini di `risk_score`) in base al device sul quale chiama la API.

Potrebbero esserci dei casi in cui l’app dà la possibilità all’utente di impostare la temperatura, quindi il parametro `perc` dell’API è una variabile, il cui valore cambia in base all’input dell’utente.
In questo caso, secondo me, dato che il valore della variabile può assumere tutti i valori da 0 a 100, bisogna considerare il valore 100 per impostare il `risk_score`.

Prendendo WoT, un esempio di Thing Decription per un forno è il seguente (modificato da [questo](https://www.w3.org/TR/wot-thing-description11/#simple-thing-description-sample)):

{
    "@context": "http://www.w3.org/ns/td",
    "id": "urn:dev:ops:32473-WoTOven-1234",
    "title": "MyOvenThing",
    "securityDefinitions": {
        "basic_sc": {"scheme": "basic", "in": "header"}
    },
    "security": "basic_sc",
    "properties": {
        "status": {
            "type": "string",
            "forms": [{"href": "https://myoven.example.com/max_temp”}]
        }
    },
    "actions": {
        “on”: {
            "forms": [{"href": "https://myoven.example.com/on”}]
        },
        “off”: {
            "forms": [{"href": "https://myoven.example.com/off”}]
        }
    },
    "events":{
        "overheating":{
            "data": {"type": "string"},
            "forms": [{
                "href": "https://myoven.example.com/oh",
                "subprotocol": "longpoll"
            }]
        }
    }
}

La nostra API dovrebbe wrappare una `action` e prendere il valore da una delle `properties` per poi calcolare il `risk_score`.

> [name=Luca Barbato]
> L'estensione più semplice sarebbe aggiungere le nostre label nei `forms` per l'autodescrizione e sul lato applicazione-in-dispositivo avere delle derivazioni di `Action` che includano in un modo o nell'altro le label.
> Sul lato applicazioni-su-altro aka UI l'applicazione in un modo o nell'altro deve esporre le sue query per i device (`voglio i forni`, `voglio il mondo`) e per le funzionalità per-label (`mostrami tutte le proprietà esplosive del dispositivo`) e poi in ultimo cosa vuole farci (`voglio leggerle`, `voglio scriverle`).
> a seconda di come scriviamo l'API applicativa questo può essere più o meno facile, ma sempre fattibile (per fortuna).

{
    "@context": "http://www.w3.org/ns/td",
    "id": "urn:dev:ops:32473-WoTOven-1234",
    "title": "MyOvenThing",
    "securityDefinitions": {
        "basic_sc": {"scheme": "basic", "in": "header"},
        "sifis": {"scheme": "sifis", "..."}
    },
    "security": ["basic_sc", "sifis"],
    "properties": {
        "status": {
            "type": "string",
            "forms": [{
                "href": "https://myoven.example.com/max_temp”,
            }]
        }
    },
    "actions": {
        “on”: {
            "forms": [{
                "href": "https://myoven.example.com/on”,
                "safety": [{
                    "name": "FIRE_HAZARD"
                    "description": "The execution may cause fire.",
                    "risk_score": 0.9
                }, {
                    "name": "POWER_OUTAGE",
                    "description": "High instantaneous power. The execution may cause power outage.",
                    "risk_score": 0.8
                }]
            }]
        },
        “off”: {
            "forms": [{"href": "https://myoven.example.com/off”}]
        }
    },
    "events":{
        "overheating":{
            "data": {"type": "string"},
            "forms": [{
                "href": "https://myoven.example.com/oh",
                "subprotocol": "longpoll"
            }]
        }
    }
}

Plugin IDE evitato se facciamo approccio statico definito da @lu-zero e questo lo prepariamo per il mese 18 (Marzo). Cerchiamo un progetto simile che implementa questo approccio e ce lo modifichiamo --> approccio più veloce

Approccio dinamico (aggiornamento in base a date) lo possiamo elencare o farci un mockup

Il tool che prende le json label e unisce tutto insieme in un metadata e via.