Sul web sono presenti un gran numero di servizi che offrono delle API per poterne sfruttare le funzionalità. In genere il trasferimento dei dati avviene tramite JSON. In questo post vediamo come creare una struttura JSON inviare ad un servizio API e leggerne la risposta. Ma possiamo usare la stessa tecnica anche tra applicazioni Xojo.

JSON

Prima di tutto vediamo cos’è JSON. Questa sigla sta per JavaScript Object Notation ed è la struttura generalmente utilizzata in Javascript per serializzare (vale a dire trasformare in testo un oggetto o una struttura Javascript.

Ma questo formato non è necessariamente legato al solo Javascript, può essere comunque utilizzato in varie occasioni per comunicare con un server per sfruttarne delle API o in ogni caso con altre applicazioni distinte da quella che si sta sviluppando.

Un formato alternativo è, ad esempio, XML che lo stesso permette di creare una struttura in formato testo che è la rappresentazione di una struttura dati.

Il vantaggio di XML è di essere un formato facilmente leggibile dagli umani, quello di JSON è di essere molto più compatto e di richiedere una libreria per la sua analisi, per trasformare la struttura testuali in struttura dati, decisamente più leggera.

Struttura di un JSON

Come detto JSON è un formato testuale per cui non sono ammessi dati binari, anche se possiamo sempre introdurli dopo averli trasformati in testo ad esempio con una trasformazione base64.

La sua definizione è un standard (ECMA-404) e prevede che una struttura JSON sia un oggetto o un vettore.

Un oggetto è un insieme, anche vuoto, di associazioni stringa : valore, mentre un vettore è una sequenza, anche vuota, di valori.

Un valore invece può essere: una stringa, un numero, un booleano, null (ad indicare nessun oggetto); ma anche un vettore o un oggetto:  per cui è possibile realizzare strutture molto complesse.

Una stringa può contenere qualsiasi carattere con l’eccezione dei doppi apici (che devono essere scritti con il backslash prima) e del backslash (che viene scritto come doppio backslash). Questo perché i doppi apici e il backslash sono utilizzati all’interno della struttura JSON: i doppi apici per indicare l’inizio e la fine di una stringa, il backslash per indicare una sequenza di caratteri da interpretare diversamente.
Tra gli altri caratteri non scrivibili direttamente abbiamo i caratteri di controllo che devono essere scritti come backslash seguito dal carattere che indica il carattere di controllo: ad esempio \t per la tabulazione. I caratteri UNICODE possono essere scritti nella forma \uhhhh dove h è una cifra esadecimale.

I numeri sono scritti come sequenza di caratteri numerici, con il punto come separatore dei decimali e nessun separatore per le migliaia, ed è ammessa anche la notazione scientifica.

I valori booleani sono scritti come: true e false.

Ma tutto questo ci serve solo per poter leggere il testo che una struttura JSON rappresenta. In Xojo abbiamo il generatore (che trasforma una struttura in un testo JSON) e l’interprete (che trasforma una testo JSON una struttura dati).

Creare un JSON in Xojo

Dalla definizione di un JSON possiamo vedere immediatamente la sua analogia con un Dictionary o un vettore di Dictionary. Per cui per ottenere un JSON dobbiamo prima creare una struttura dati come Dictionary o Dictionary() che poi andremo a trasformare.

Una volta ottenuto il nostro Dictionary o vettore di Dictionary, o altri tipi di dati primitivi accettabili, possiamo utilizzare la funzione del nuovo framework Xojo.Data.GenerateJSON che accetta entrambi i tipi di argomento.

//Definiamo unDictionary come oggetto Dictionary
Dim unDictionary as Xojo.Core.Dictionary
//poi lo popoliamo secondo le nostre necessità
 
//Definiamo vDictionary come vettore di oggetti Dictionary
Dim vDictionary() as Xojo.Core.Dictionary
//poi andremo ad aggiungere i vari Dictionary secondo le nostre necessità
 
//Per i vettori possiamo usare anche array di numeri, booleani o Text.
Dim vInteri() as Integer
Dim vBool() as Boolean
Dim vText() as Text
//Che poi possiamo popolare secondo le nostre necessità.
 
//Generiamo i vari JSON
Dim tUnDictionary as Text=Xojo.Data.GenerateJSON(unDictionary)
Dim tVDictionary as Text=Xojo.Data.GenerateJSON(vDictionary)
Dim tVInteri as Text=Xojo.Data.GenerateJSON(vInteri)
Dim tVBool as Text=Xojo.Data.GenerateJSON(vBool)
Dim tVText as Text=Xojo.Data.GenerateJSON(vText)

Chiaramente il contenuto dipende dall’uso che ne dobbiamo fare.

JSON è solo testo

Bisogna sempre ricordarsi che JSON è un formato solo testuale per cui se dobbiamo usare all’interno di una struttura JSON dati più complessi (ad esempio una data o un’immagine) dobbiamo utilizzare altre strategie che possono dipendere dal servizio o dall’uso.

Ad esempio per un’immagine potrebbe bastare indicare l’indirizzo web da cui recuperarla (o del server su rete interna per un’applicazione locale). Se è necessario inviare il contenuto dell’immagine allora dobbiamo trasformarla in testo tramite EncodeBase64 o EncodeHex. Se stiamo utilizzando il nuovo Framework basta rendere le stringhe ottenute dei Text con .ToText, se siamo su iOS dobbiamo utilizzare le Declare equivalenti che sono disponibili in rete.

Per le date, se abbiamo utilizzato Date basta utilizzare .sqlDate o .sqlDateTime (a seconda delle necessità) per poter ottenere la stringa utilizzabile (sempre da trasformare con .ToText), se invece utilizziamo il nuovo Framework è possibile utilizzare direttamente .ToText per ottenere l’equivalente di SQLDateTime o prenderne solo i primi 10 caratteri per ottenerne l’equivalente di SQLDate.

Leggere un JSON in Xojo

Ovviamente possiamo fare l’operazione inversa, vale a dire trasformare un testo che è una struttura JSON in una variabile direttamente gestibile in Xojo.

Dim variabile as Auto=Xojo.Data.ParseJSON(testoJSON)

Occorre notare che il risultato di ParseJSON è di tipo Auto, che è il variant tipizzato del nuovo framework, cioè un tipo che può rappresentare diverse tipologie di dato, ma una volta assegnato non possiamo convertirlo direttamente in un tipo diverso.

In questo caso, come abbiamo già detto, l’elemento base può essere un oggetto o un vettore, quindi o un Dictionary o un vettore di Auto (ancora una volta una definizione ricorsiva).

La scelta in fase implementativa è data dal sapere già che dato ci aspettiamo e quindi gia ci aspettiamo che il dato sia del tipo giusto. Se non lo è probabilmente stiamo leggendo un JSON che non è quello che dovremmo leggere per cui dobbiamo gestire una eccezione.

Una eccezione va in ogni caso gestita perché lo stesso testoJSON potrebbe essere, venendo in genere da fonte esterna, non corretto (vale a dire che è solo una sequenza di caratteri e non un JSON vero e proprio.