API
Smartbiogas (SB) ha un sistema di API che può essere usato per:
- Integrare un proprio sistema per leggere i dati delle anagrafiche di SB
- Substrati
- Paesi e Città europee utilizzati nelle nostre anagrafiche
- Soggetti
- Unità di misura
- Tipi di analisi e parametri
- Inserire in modo automatizzato carichi e scarichi di magazzino, o le misure da dei sensori
- Inserire i risultati delle analisi
L'utilizzo non è pubblico, sia per motivi di sicurezza e privacy dei dati, sia per controllare la provenienza dei dati.
E' necessario richiedere al team di SB che il proprio o i propri indirizzi pubblici da cui partiranno le richieste vengano messi nella whitelist. Di default ogni richiesta darà errore di IP non autorizzato.
la rotta principale per l'accesso alle API di SB è (ad oggi è presente la versione 1):
esempio per vedere la lista di substrati:
GET https://smartbiogas.it/api/v1/feedstocks_type
Oltre al whitelist deil proprio IP Pubblico per alcune risorse collegate ad un impianto in particolare (ad esempio Magazzini e movimenti di magazzino) è necessaria che venga fornita una chiave di 128 caratteri che inserisce un ulteriore livello di sicurezza e allo stesso tempo definisce in modo univoco l'impianto su cui si andrà a lavorare.
Tale chiave deve essere presentata nell'HEADER della richiesta come nell'esempio:
X-API-TOKEN: FpEycf3HmcML6Hv4qsjZBXroeWoKGyHyTMZKRO1cekFQkCADoScp5RYXjtrlQvoD5BJhVepaRjruzgux4yfVzq3pBOVoHxybA2Jc1Iu0oyBHMdRiJcjFigLtOtRUCRd1
Ogni route cerca di sottostare allo standard, usando i verbi GET, POST, PATCH
In generale la regola per le route è:
| VERBO | Route | Note |
|---|---|---|
| GET | https://smartbiogas.it/api/v1/[Risorsa] | restituisce la lista delle risorse |
| GET | https://smartbiogas.it/api/v1/[Risorsa]/{id risorsa} | Restituisce i dati di una risorsa in particolare |
| PATCH | https://smartbiogas.it/api/v1/[Risorsa]/{id risorsa} | Laddove è permesso aggiorna con i dati passati in un json la risorsa su SB |
| POST | https://smartbiogas.it/api/v1/[Risorsa] | laddove è permesso inserisce una nuova risorsa su SB |
Esistono routes annidate in questo modo
https://smartbiogas.it/api/v1/[Risorsa]/{id risorsa}/[Sotto risorsa]
Ad esempio
GET https://smartbiogas.it/api/v1/countries/19/cities che restituisce l'elenco dei comuni nel paese italia (id 19)
Alcune API possono utilizzare diversi parametri di ricerca
Esempio
GET https://smartbiogas.it/api/v1/countries/19
GET https://smartbiogas.it/api/v1/countries?f_cod=IT
GET https://smartbiogas.it/api/v1/countries?f_description=ital (questo fa una ricerca testuale e in questo caso trova solo Italy, ma è possibile ricercare per parti di descrizione ottenendo più risultati)
Tutte e 3 danno lo stesso risultato, li primo trova per id, il secondo per codice, il terzo per descrizione
Risultati
[edit | edit source]Nelle Api che chiedono record di tabelle in generale il formato è il json.
Esempio di json restituito da
GET https://smartbiogas.it/api/v1/countries?f_description=it
[
{
"eu_countries_id": 19,
"f_cod": "IT",
"f_description": "Italy"
},
{
"eu_countries_id": 21,
"f_cod": "LT",
"f_description": "Lithuania"
}
]
Le Api possono anche restituire degli errori. In generale il formato dell'errore è:
{
"error_code": 13,
"message": "Not Found"
}
Per le api di inserimento/aggiornamento verrà restituito un json simile
{
"error_code": 0,
"movement_id": 4578693,
"message": "Movement inserted correctly"
}
Elenco Api di anagrafiche generali del sistema
[edit | edit source]Soggetti/Subjects (Persone Fisiche con PIVA o Aziende)
Gruppi e tipi di unità di misura
Determinandi (Anagrafica dei parametri comuni a tutte le analisi)
LE seguenti API hanno un accesso ristretto ad enti o aziende che devono produrre dati per molti impianti (tipo Laboratori di analisi)
Le seguenti API richiedono la chiave identificativa dell'impianto (X-API-TOKEN) e daranno risultati relativi al collegamento con l'impianto stesso.