Sviluppatori

SERVIZIO ENDPOINT

Github Repo:

BibleGet I/O provvede un API utilizzabile dalle applicazioni, in modo che possano 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.

Documentazione Swagger / Open API

(completa con sezioni interattive “Fai una prova”)  https://www.bibleget.io/swaggerdocs/dist

(kudos a Michael Shelton per aver generato i documenti a partire dalla definizione in openapi.json !)

ENDPOINT URL

Il principale url su cui effettuare le richieste è https://query.bibleget.io/ (che corrisponde a https://www.bibleget.io/query/). Il motore permette di effettuare richieste utilizzando i nomi dei libri della Bibbia in diverse lingue (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”.
• “appid”: (opzionale) si tratta del nome identificativo dell’applicazione o plugin che effettua le richieste al servizio. Sebbene sia opzionale, si prega utilizzarlo con un nome univoco per tutte le richieste che saranno effettuate dall’applicazione. In futuro potrebbe essere necessario registrarsi con un nome identificativo dell’applicazione per poter utilizzare il servizio
• “pluginversion”: (opzionale) si tratta della versione dell’applicazione o del plugin che effettua le richieste al servizio. Sebbene sia opzionale, si prega indicarlo quando viene indicato il parametro “appid”, insieme questi due parametri aiutano ad identificare le richieste che vengono fatte al servizio. In futuro potrebbe diventare obbligatorio, se per esempio un’applicazione viene aggiornata per motivi di sicurezza e non è il caso di usare più una versione precedente di quell’applicazione o di quel plugin, si potranno negare richieste che provengono da una versione obsoleta
• “domain”: (opzionale) si tratta di un parametro che aiuta ad identificare il sito da cui proviene una richiesta. Per esempio nel caso del plugin per WordPress viene registrato il dominio del sito nel quale il plugin viene utilizzato. Questo parametro aiuta ulteriormente a monitorare l’utilizzo del servizio, visto che al momento non c’è un sistema di registrazione che permetta l’utilizzo.

METADATA ENDPOINT

Il Progetto BibleGet offre un altro endpoint che permette di richiedere i “metadati” riguardo alle versioni bibliche attualmente supportate dal motore BibleGet, come anche le indici dei capitoli e dei versetti per ognuna di queste versioni. L’endpoint dei “metadati” è https://query.bibleget.io/metadata.php. I parametri per inviare le richieste all’endpoint dei metadati sono:

• “query”: (obbligatorio) Il parametro “query” accetta uno di tre valori:
  • “biblebooks”: restituisce dati riguardo all’elenco dei nomi dei libri della bibbia insieme alle loro abbreviazioni, che possono essere utilizzati per effettuare le query all’endpoint principale.
  • “bibleversions”: restituisce dati riguardo alle versioni bibliche attualmente supportate dal motore BibleGet.
  • “versionindex”: restituisce dati riguardo alle indici dei capitoli e dei versetti per ognuna delle versioni bibliche attualmente supportate dal motore BibleGet. Questo valore richiede il parametro “versions” insieme al parametro “query”.
• “versions”: (obbligatorio quando è utilizzato il valore “versionindex” per una richiesta con il parametro “query”). Questo parametro indica le versioni bibliche per le quali restituire i dati delle indici. Il valore del parametro può essere sia una singola versione biblica oppure multiple versioni indicate come elenco di valori concatenati da virgola. I valori possibili per le versioni bibliche si possono ottenere con la richiesta utilizzando il parametro “query” con valore “bibleversions”.
• “return”: (opzionale) indica il formato nel quale i dati strutturati dovrebbero essere restituiti. Questo parametro può avere uno di questi tre valori: “json”, “xml”, o “html”. Se non indicato, verranno restituiti dati in formato “json”.

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: https://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: https://query.bibleget.io/?query=Mt1,1-10;2,2-4&return=json.

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

CACHE DELLE RICHIESTE AL SERVIZIO

Visto che il contenuto delle risposte non sono valori dinamici, ma sono valori piuttosto statici (i testi biblici è difficile che cambino), è bene che le applicazioni che effettuano richieste all’endpoint utilizzino dei meccanismi di cache locale, soprattutto quando si tratta di siti o pagine web che possano essere aperte e consultate dal pubblico generale. Bisogna tenere conto che senza un meccanismo di cache, la pagina web effettuerà una nuova richiesta al servizio BibleGet ogni volta che la pagina viene aperta. Un utilizzo poco considerato potrà facilmente generare migliaia di richieste inutili al servizio, soprattutto se queste pagine sono indicizzate dai motori di ricerca. Gli stessi motori di ricerca quando effettuano lo scrape della pagina innescheranno una nuova richiesta all’endpoint, inutilmente!

Nel plugin per WordPress per esempio, ho utilizzato i transient di WordPress per memorizzare in locale le risposte alle richieste generate dagli shortcode. In questo modo, quando un utente apre una pagina nella quale la richiesta è stata effettuata precedentemente, verrà utilizzata la risposta memorizzata nel transient anziché effettuare una nuova richiesta all’endpoint. Questo tipo di utilizzo considerato permetterà al progetto di sopravvivere e venire utilizzato sempre di più. Attualmente il motore dell’endpoint effettua alcune verifiche: se vengono effettuate troppe richieste per la stessa query da una stessa sorgente (per esempio da una stessa pagina web), verranno dati degli avvisi o verrà addirittura negato il servizio. Se questo progetto continuerà a crescere, con ogni probabilità diventerà necessario registrarsi per ottenere una chiave API che permetterà ad un’applicazione di effettuare le richieste, e verrà monitorato l’utilizzo.