Oracle Database parla REST/JSON … e da tempi non sospetti!

Nel 2010, quando le tecnologie afferenti ai microservizi erano ancora un tema da convegni per addetti ai lavori e le aziende erano in piena fase di implementazione di architetture SOA utilizzando i web services, Oracle introduceva in APEX una funzionalità che poi diventò la prima versione di Oracle REST Data Services (ORDS), uno strumento che permette di esporre i dati presenti nel database utilizzando API REST senza la necessità di sviluppare codice.

Successivamente, nel 2014, la release 12.1 di Oracle Database ha esteso ORDS introducendo Simple Oracle Document Access (SODA), uno strumento che consente di creare e archiviare raccolte di documenti (oggetti JSON) nel database Oracle, permettendo di recuperarli e interrogarli via REST in maniera indipendente dalla modalità con cui i dati vengono archiviati nel database.

Approfondiamo le funzionalità di questi due strumenti, che si dimostrano molto utili nell’intero ciclo di vita del software — dallo sviluppo alla produzione.

Oracle REST Data Services (ORDS)

ORDS fornisce strumenti per la generazione di API REST che accedono a singole tabelle e viste, o che estraggono dati più complessi, producendo in output veri e propri documenti JSON complessi. E’ possibile eseguire semplici statement SQL, stored procedures o query SQL articolate che usano JOIN e CURSOR, eseguendo automaticamente il mapping dei dati sia in ingresso che in uscita.

Il mapping tra i verbi REST e le operazioni lato DB utilizzano il seguente schema:

mentre la URI è costruita secondo questo schema:

dove il Context Root si riferisce ad una particolare istanza del database: è infatti possibile avere un’unica istanza di ORDS e collegarsi a più database. Il suffisso Module identifica uno gruppo di API relative (per esempio) ad uno schema, ed il successivo Template rappresenta uno specifico nome che identifica un pattern all’interno di un Module per il quale si possono implementare i quattro verbi GET,POST,PUT e DELETE.

La VM Big Data Lite, di cui esiste un’immagine Virtualbox disponibile al link http://www.oracle.com/technetwork/database/bigdata-appliance/oracle-bigdatalite-2104726.html, è un ottimo esempio che include una serie di tecnologie che possono essere esplorate praticamente: la base dati del MoviePlex Store, un negozio online dove è possibile accedere ad un catalogo di film disponibili per la visione (vi ricorda qualcosa?), espone attraverso API REST l’accesso al catalogo effettuando una GET (anche da browser) all’indirizzo http://127.0.0.1:70780/ords/moviedemo/movie/1054798 , che permette di otterrete il seguente output:

{
"movie_id": 1054798,
"title": "Crank: High Voltage",
"year": 2009,
"budget": 20000000,
"gross": 34560577,
"plot_summary": "Crank: High Voltage (promoted as Crank 2: High Voltage in some regions and on DVD) is a 2009 American action film and sequel to the 2006 action film, Crank. The story of the film resumes shortly after the first film left off, retaining its real-time presentation and adding more special effects. Crank: High Voltage was written and directed by Mark Neveldine and Brian Taylor, who both wrote and directed the previous film. The film was released in the United Kingdom on April 15, 2009, two days prior to its North American release date.",
"links": [
{
"rel": "self",
"href": "http://127.0.0.1:7070/ords/moviedemo/movie/1054798"
},
{
"rel": "edit",
"href": "http://127.0.0.1:7070/ords/moviedemo/movie/1054798"
},
{
"rel": "describedby",
"href": "http://127.0.0.1:7070/ords/moviedemo/metadata-catalog/movie/item"
},
{
"rel": "collection",
"href": "http://127.0.0.1:7070/ords/moviedemo/movie/"
}
]
}

I parametri utilizzabili per la creazione di query dinamiche (es. SELECT * from movie WHERE movie_id = 1054798) possono essere impostati in diversi modi e dipendono dallo specifico verbo REST:

  • GET e DELETE: è possibile specificare i parametri nella URI usando la query string o come parte della URI stessa come nell’esempio di cui sopra.
  • POST: utilizzo del body specificando l’header Content-Type:application/json”
  • PUT: come nel caso della GET il parametro viene usato per identificare il record da modificare ed il body come nel caso della POST per passare i parametri da aggiornare.

Nell’ultima versione di ORDS, parte di Oracle DB 18 appena rilasciato, è stato aggiunto il supporto a Swagger 2.0, ovvero la capacità di esportare il catalogo di API definite in formato OpenAPI. Usando ad esempio una GET alla URI http://127.0.0.1:7070/ords/moviedemo/open-api-catalog/movie si ottiene in output un documento JSON che può essere utilizzato da strumenti di API Design come Apiary:

Troverete ulteriori approfondimenti nei manuali ufficiali http://docs.oracle.com: personalmente, consiglio gli ottimi articoli scritti da Tim Hall che trovate al link https://oracle-base.com/articles/misc/articles-misc#ords, a partire dal tutorial iniziale Create Basic RESTful Web Services Using PL/SQL.

Simple Oracle Document Access (SODA)

Se ORDS si basa su uno specifico schema formato da tabelle e modelli Entity/Relationship, con SODA è possibile memorizzare documenti JSON senza specificare dove quest’ultimo viene memorizzato, secondo uno approccio “schema-on-read” (chi legge il dato conosce dove si trovano le informazioni), dove si usa esclusivamente l’interfaccia REST/JSON.

In SODA esiste il concetto di collection come per tutti i comuni Document DB e le operazioni sono definite dalla combinazione di verbo REST e di URI, secondo la tabella seguente:

La URL ha un prefisso comune, come descritto precedentemente nelle funzionalità di ORDS, per tutte le operazioni:

dove il Context Root riferisce ad una particolare istanza del database (è possibile avere un’unica istanza di SODA e collegarsi a più database), lo Schema identifica uno schema all’interno di un database, latest una specifica versione del record seguito dal nome della collection.

Ad esempio, utilizzando il comando:

curl -i -X PUT http://localhost:7070/ords/moviedemo/soda/latest/postakcollection

è possibile creare la collection postakcollection, mentre con il comando:

curl -X POST --data-binary @po.json -H "Content-Type: application/json" http://localhost:7070/ords/moviedemo/soda/latest/postakcollection

inseriamo un record nella collection. Il file po.json specificato con l’opzione --data-binary, contiene il seguente JSON che rappresenta il dato memorizzato:

{
"firstName": "Luca",
"lastName": "Postacchini",
"age": 25,
"address": {
"streetAddress": "Via Amsterdam",
"city": "Roma",
"state": "RM",
"postalCode": "00144",
"isBusiness": true
},
"phoneNumbers": [
{
"type": "mobile",
"number": "123456789"
},
{
"type": "office",
"number": "987654321"
}
]
}

Come avete visto, con SODA possiamo quindi utilizzare Oracle Database proprio come un Document DB e interagire esclusivamente via REST utilizzando JSON, secondo gli ultimi pattern di sviluppo del mondo dei microservizi.

Il punto di forza di questa tecnologia, però, è proprio la disponibilità di un ponte tra le tecnologie (e le competenze) già presenti in azienda e l’adattamento richiesto da stili architetturali più moderni ed orientati a funzioni di granularità molto fine.

Infatti, il record precedentemente inserito nella collection postakcollection può essere letto via SQL usando la seguente sintassi:

SQL> SELECT c.json_document.firstName, c.json_document.lastName, c.json_document.address.streetAddress,
c.json_document.phoneNumbers.num
FROM postakcollection c
WHERE c.json_document.age > 20;
FIRSTNAME    LASTNAME      ADDRESS         PHONENUMBERS
------------ ------------- --------------- -------------------------
Luca Postacchini Via Amsterdam ["123456789","987654321"]

Conclusioni

ORDS e SODA rappresentano due tecnologie cardine utilizzabili, con profitto, sia in ambienti tradizionali dove la struttura in grado di alloggiare i dati è definita a priori — un approccio schema-on-write- sia in ambienti dove l’utilizzo di uno stile architetturale più moderno (ad esempio, il pattern database-per-service dei microservizi) può richiedere una visione a lungo termine corrispondente allo schema-on-read.

Ci riferiamo molto spesso a questa elasticità come ad un servizio di polimorfismo per dati, che non sempre le tecnologie correnti sono in grado di supportare.

Al link http://www.oracle.com/technetwork/database/application-development/oracle-document-store troverete diversi documenti, whitepaper ed un collegamento ad un progetto su GitHub con diversi esempi di applicazioni scritte in java, python e node che utilizzano ORDS e SODA, e che — probabilmente — nel 2018 non possiamo fare a meno di approfondire.