Sviluppare con la RESTful API

Scoperta e accesso

Introduzione

REST (REpresentational State Transfer) è uno stile architetturale per l’implementazione di sistemi per la condivisione di risorse. Secondo il suo ideatore, REST è lo stile architetturale originale e proprio del World Wide Web. Il World Wide Web è utilizzato come infrastruttura generica per fornire servizi di rete secondo diversi stili architetturali. Ciò nonostante negli ultimi anni, c’è stato un notevole interesse nel fornire servizi in modo pienamente conforme allo stile architetturale REST. Pertanto molti sistemi Web forniscono accesso alle loro funzionalità mediante cosiddette API RESTful. Benché il concetto di API (Application Programming Interface) non si applichi rigorosamente allo stile REST, il termine RESTful API è comunemente utilizzato per riferirsi ad un modo di interazione con un sistema software mediante messaggi di richiesta e risposta diretti a risorse identificate da un URI (Uniform Resource Identifier). Nelle RESTful API il contenuto dei messaggi è solitamente codificato in XML o JSON.

 

L’ENERGIC OD VH segue questa tendenza fornendo un semplice modo di interagire con l’hub scambiando messaggi JSON con risorse identificate da URI.

 

Conformemente con lo stile architetturale REST, la RESTful API del VH dà accesso diretto a risorse supportando il pattern Create-Retrieve-Update-Delete (CRUD).

Le principali risorse esposte dalla RESTful API sono:

 

• Sources: la lista di fonti (sources) connesse al VH

• Datasets: la lista di dataset accessibili attraverso il VH

• Dataset: il singolo dataset

 

Secondo i vincoli REST, ogni risorsa è identificata da un URI. Nella RESTful API, l’URI di una risorsa include un endpoint base (http://vh-it.energic-od.eu/gi-cat/services/api-rest) e un percorso mnemonico definito convenzionalmente:

 

• Sources              http://vh-it.energic-od.eu/gi-cat/services/api-rest/sources

• Datasets            http://vh-it.energic-od.eu/gi-cat/services/api-rest/datasets

• Dataset              http://vh-it.energic-od.eu/gi-cat/services/api-rest/datasets/{id}

 

Dove {id} deve essere sostituito con l’ID specifico del dataset.

 

Ogni risorsa supporta una o più azioni CRUD implementate come richieste HTTP. Per esempio, per recuperare la lista di fonti, l’utente deve inviare una richiesta HTTP GET a  http://vh-it.energic-od.eu/gi-cat/services/api-rest/sources:

 

    GET     http://vh-it.energic-od.eu/gi-cat/services/api-rest/sources

 

L’utente riceve un messaggio JSON che include le informazioni sulle fonti di dati commesse al VH:

 

{

 "resultSet": {

"size": 7,

"start": 1,

"pageSize": 7,

"pageCount": 1,

"pageIndex": 1

 },

 "reports": [

{

  "id": "GBIF",

  "type": "composed",

  "title": "GBIF",

  "harvested": false

},

{

  "id": "WEBSRVENCAT",

  "type": "composed",

  "title": "Webservice Energy Catalog",

  "harvested": true

},

{

(…continue…)

​

 

La Figura X mostra un sottoinsieme del modello di risorse ENERGIC OD, con l’interazione diretta alle risorse resa possibile mediante verbi HTTP.