REST API

Oltre alle API viste nelle lezioni precedenti, OrientDB permette l'utilizzo di API REST, che sfruttano il formato JSON per lo scambio dei dati. Tale caratteristica offre l'opportunità di interagire con il DBMS mediante qualsiasi tecnologia che sia in grado di trattare il protocollo HTTP. In questa lezione, le sperimenteremo senza l'intermediazione di alcun linguaggio di programmazione, ma solo tramite un client disponibile come estensione del browser Chrome, Postman, ideale per i test. Per comprendere appieno la lezione, occorre
una minima conoscenza della metodologia REST.

Essenzialmente, si tratterà di inviare richieste HTTP specificando il metodo del protocollo più adatto all'operazione da svolgere: GET per effettuare una lettura, POST per l'inserimento di dati, PUT per la modifica e DELETE per la cancellazione. Alla richiesta, potranno essere allegate informazioni da fornire al DBMS, ove necessarie, mentre l'URL contattato indicherà la risorsa cui fare accesso. Leggeremo infine la risposta del server in formato JSON notando, in primis, il codice di ritorno che ci confermerà o meno la buona riuscita dell'operazione. Si ricordi a tal proposito che i codici di risposta HTTP sono numeri di tre cifre: se la prima è 2 indica un'attività svolta con successo, se è pari a 4 rileva un errore del client, se il codice inizia con 5 segnala tipicamente un errore interno al server.

Supporremo, negli esempi che seguiranno, di avere a disposizione un'istanza funzionante ed in esecuzione di OrientDB all'indirizzo http://192.168.1.100, già contenente un database di nome nuovodb. Per riprodurre, gli esempi sui propri sistemi sarà pertanto necessario sostituire negli URL questi dati con quelli opportuni.

Connessione e disconnessione

Le attività di lavoro vanno inquadrate in una sessione per la quale si può richiedere l'apertura della connessione e la disconnessione. Entrambe le richieste sfruttano il metodo GET:

• la connessione al database nuovodb si potrà attuare nella seguente maniera:
  

  http://192.168.1.100:2480/connect/nuovodb

  
  sfruttando la Basic Authentication per l'immissione dei parametri. Quest'ultima funzionalità è offerta da Postman. Il codice di ritorno sarà 204 per un login effettuato con successo, o 401 in caso contrario;
• la disconnessione può essere richiesta come segue:
  

  http://192.168.1.100:2480/disconnect

Lavorare con i documenti

Una volta connessi potremo creare una nuova classe nel database, tramite una richiesta di tipo POST:

http://192.168.1.100:2480/class/nuovodb/Persona

Se la creazione va in porto, nella risposta HTTP troveremo il codice 201 che notifica l'avvenuta creazione della risorsa. Proviamo ora ad inserire dei documenti nella nuova classe. Anche in questo caso si tratterà di una richiesta POST:

http://192.168.1.100:2480/document/nuovodb

dove riempiremo il corpo della richiesta con un oggetto JSON in cui riporremo il nome della classe nel campo @class e le restanti informazioni in tutti gli altri campi.

Un aspetto interessante è che il corpo della risposta HTTP conterrà l'oggetto JSON appena inserito (quindi i dati forniti da noi) con l'aggiunta di alcuni campi, tra cui @rid che contiene l'ID del nuovo elemento. Inseriremo in questo modo altri due documenti e procederemo con una query per verificarne effettivamente i risultati.

http://192.168.1.100:2480/query/nuovodb/sql/select from Persona

La query sarà effettuata come richiesta GET e come ultimo parametro includerà il codice SQL che la definisce. Come risultato, la risposta HTTP porterà un array di oggetti JSON rappresentanti i vari record salvati:

I metodi HTTP - PUT e DELETE - serviranno, rispettivamente, per eseguire i comandi di UPDATE e DELETE. Ad esempio, per cancellare il record con RID #10:2 si eseguirà la seguente richiesta DELETE:

192.168.1:100:2480/document/nuovodb/10:2

L'ultimo parametro che verrà accodato è il RID nel quale si dovrà omettere il simbolo #. Il metodo PUT permetterà di modificare un singolo record ed i nuovi dati saranno passati nel corpo della richiesta, anche questa volta in formato JSON. Un aspetto interessante da notare è che si può indicare la modalità con cui eseguire la modifica: il default sarà il cosiddetto full mode, che rimpiazza totalmente il record, mentre il partial mode applicherà solo le differenze.

Manipolare database e classi

Oltre a questi primi esperimenti, le API REST offrono l'opportunità di chiedere informazioni o commissionare modifiche a tutti i principali elementi di OrientDB. Per quanto riguarda i database, una GET di questo tipo:

http://192.168.1:100:2480/database/nuovodb

permetterà di leggere le informazioni relative al database nominato come ultimo campo dell'URL riassumendone caratteristiche del sistema operativo (comprese alcune relative alla Java Virtual Machine in uso), classi e cluster, utente corrente ed i parametri di configurazione.

Una POST di questo tipo:

http://192.168.1:100:2480/database/databasenuovo/plocal

permetterà di creare un nuovo database. Si noti che deve essere specificato come ultimo parametro il tipo di memorizzazione.

Abbiamo già visto la creazione di una classe, ma è bene comunque notare che una GET come la seguente:

http://192.168.1.100:2480/class/nuovodb/Persona

permette di ottenere informazioni sulla classe Persona, inclusi numero di record e cluster che la compongono.

La classe, così usata, non ha proprietà obbligatorie, e ne abbiamo fatto un uso non strutturato. Se volessimo creare una nuova proprietà, potremmo usare una richiesta POST di questo tipo:

http://192.168.1.100:2480/property/nuovodb/Persona/datanascita

che aggiungerà una nuova proprietà alla classe Persona di nome datanascita. Eseguendo ancora una volta, a questo punto, la GET per ottenere le informazioni sulla classe, troveremmo anche un array di oggetti JSON, contraddistinto dall'etichetta properties, che elenca le proprietà della classe con tanto di caratteristiche:

"properties": [
    {
      "name": "datanascita",
      "type": "STRING",
      "mandatory": false,
      "readonly": false,
      "notNull": false,
      "min": null,
      "max": null,
      "regexp": null,
      "collate": "default"
    }
  ]

Ulteriori funzionalità

Altre proprietà delle API REST permettono di gestire indici, eseguire funzioni ed attivare comandi: la pagina dedicata della documentazione ufficiale mette a disposizione tutte le informazioni necessarie. L'utilità di queste API consiste soprattutto nel poter creare proprie librerie che permettano di interagire con OrientDB tramite qualsiasi linguaggio di programmazione. Si ricordi, comunque, che le prestazioni possono essere ulteriormente migliorate rivolgendosi all'uso del Binary protocol, come accennato in una lezione precedente.