Sviluppatori

SERVIZIO ENDPOINT

BibleGet I/O utilizza un servizio di tipo “Endpoint” sul proprio server che viene esposto alle applicazioni, per permettere alle applicazioni di interrogare il server con una query che formula una richiesta di citazione biblica. Alla richiesta inoltrata dall’applicazione all’Endpoint, vengono restituiti dati strutturati in formato utile per la stessa applicazione (come per esempio il formato JSON che è una struttura dati propria di Javascript, ma che viene utilizzato comunemente per scambio di dati strutturati tra applicazioni o linguaggi o servizi web; un esempio di applicazione potrebbe essere un plugin per WordPress, o un’estensione per Microsoft Word, che permettono al singolo utente di effettuare citazioni automatizzate della Sacra Scrittura). In pratica il servizio Endpoint è uno script PHP che prende una query che contiene notazione standard per citazioni bibliche e la traduce in query MySQL, formattando i risultati nel formato richiesto, che può essere di tipo JSON, di tipo XML, o di tipo HTML.

ENDPOINT URL

Il principale url su cui effettuare le richieste è http://query.bibleget.io/ (che corrisponde a http://www.bibleget.io/query/). E’ ora in via di sviluppo un motore PHP più avanzato, che si trova attualmente all’URL http://query.bibleget.io/index2.php. Questo nuovo motore permette di effettuare richieste in qualsiasi lingua (i libri della Bibbia possono essere indicati in una di tante lingue diverse, attualmente sono disponibili ALBANIAN, ENGLISH, FRENCH, GERMAN, HUNGARIAN, ITALIAN, POLISH, ROMANIAN, RUSSIAN, SPANISH, TAGALOG), oltre a permettere di indicare la versione biblica desiderata.

PARAMETRI

I parametri che si possono inviare all’endpoint sono:

  • “query”*: questo parametro è obbligatorio. Il suo valore deve corrispondere ad una valida richiesta che utilizza la notazione standard per le citazioni bibliche. Si veda l’apposita sezione Notazione Standard per le Citazioni Bibliche nelle Informazioni per l’Utente.
  • “version”: (opzionale) se non viene indicato questo parametro, il valore predefinito è “cei2008”.  Con questo parametro si può indicare la versione biblica desiderata. Si possono anche indicare più versioni elencate con virgola, per confrontare testi di più versioni. Al momento sono disponibili soltanto le versioni “cei2008” e “luzzi”.
  • “return”: (opzionale) si tratta del formato nel quale si desidera che vengano restituiti i dati strutturati. Il parametro accetta uno di tre valori: “json”, “xml”, o “html”.

COME EFFETTUARE UNA QUERY ALL’ENDPOINT

La query può essere effettuata all’endpoint in vari modi:

  • da PHP, utilizzando CURL
  • da Javascript con una chiamata AJAX (che potrebbe anche utilizzare uno script PHP intermedio che utilizza CURL)
  • come attributo “src” di un elemento “iframe” in una pagina HTML (e utilizzando il parametro “return=html”)
  • qualsiasi linguaggio o applicazione che possa effettuare una chiamata ad un URL può interrogare il servizio ed elaborare poi i dati ricevuti. In Java per esempio ci sono librerie che permettono di effettuare chiamate a URL.

Esempio di query: http://query.bibleget.io/?query=Mt1,1-10;2,2-4&return=html. Prova a cliccare su questo link per vedere l’esempio dei dati restituiti, qui in formato HTML già con una minima struttura e formattazione. Ora prova con questo altro, che restituisce gli stessi dati in formato JSON, perciò senza struttura di pagina o formattazione: http://query.bibleget.io/?query=Mt1,1-10;2,2-4&return=json.

Esempio di query al nuovo motore in via di sviluppo: http://query.bibleget.io/index2.php?query=Matthäus1:1-10;2:2-4&version=cei2008,luzzi&return=html.

Puoi provare tu stesso a formulare alcune query e vedere il tipo di risposta nell’Area Sandbox.

Condividi il tuo pensiero!

%d blogger hanno fatto clic su Mi Piace per questo: