BibleGet I/O

Developers

SERVICE ENDPOINT

Github Repo: https://github.com/BibleGet-I-O/endpoint

The BibleGet I/O Project offers an API endpoint which allows applications to query the server with requests for Scripture verses using standard Bible citation notation. The request sent by the Endpoint application will return structured data in useful format for the application (such as JSON format, which is a data structure of the Javascript language, which is commonly used for exchanging structured data between applications or web services or languages). In practice the Service Endpoint is a PHP script that takes a query that contains standard notation for biblical quotations and translates it into MySQL queries, formatting the results in the required format, which can be of type JSON, XML, or HTML.

Swagger / Open API documentation

(complete with interactive “Try it yourself” sections) https://www.bibleget.io/swaggerdocs/dist

(kudos to Michael Shelton for generating the docs from the openapi.json specs!)

ENDPOINT URL

The main url for requests is https://query.bibleget.io/ (which is the same as https://www.bibleget.io/query/).
This is the scripting engine that translates requests made in standard bible citation notation into a database request and then returns the data from the database in a structured data format. The names of the books of the Bible (used in the “query” parameter) are recognized in many languages (currently ALBANIAN, ENGLISH, FRENCH, GERMAN, HUNGARIAN, ITALIAN, POLISH, ROMANIAN, RUSSIAN, SPANISH, TAGALOG).

PARAMETERS

The parameters that you send to the main endpoint are:

  • “query” *: (required) The “query” parameter must contain a valid Bible citation using standard notation, whether English notation or International notation. See the section “Standard notation for biblical quotations”.
  • “version”: (optional) If you do not specify the “version” parameter, the value defaults to the Italian “CEI2008”.  With this parameter you can specify the biblical version you want to retrieve the quote from. You can also specify several versions as a comma separated list, for example to compare multiple versions of the biblical texts.
  • “return”: (optional) The “return” parameter indicates the format in which the structured data should be returned. This parameter takes one of three values: “json”, “xml”, or “html”. If left out, this parameter will default to “json”.
  • “appid”: (required) The “appid” parameter indicates which application is generating the request. For the time being, there is no kind of api account that needs to be registered or api key or secret that needs to be generated in order for an application to send requests to the endpoint. The endpoint is completely open, but does require the “appid” parameter to know where the request is coming from. This will also be useful for the statistics of the requests made to the service endpoint, and can help monitor the usage of the endpoint. Using this parameter can be considered the basic registering mechanism for applications that make use of the service endpoint.
  • “pluginversion”: (optional) The “pluginversion” parameter lets the engine know which version of a plugin is being used to generate the request (the plugin being indicated in the “appid” parameter). Seeing that this is a project in development, and the plugins are developing together with it, in order to maintain the highest compatibility and quality assurance it is useful to know which “version” of a plugin is being used to generate the request. If for example a plugin version becomes incompatible, the engine will better determine how to handle a request coming from an outdated plugin.
  • “domain”: (optional) The “domain” parameter is also accepted by the service endpoint especially for requests that come from websites, as is the case with the WordPress plugin. This also simply helps monitor usage of the endpoint, seeing that there is no kind of application registering mechanism for the usage of the endpoint.

METADATA ENDPOINT

The BibleGet Project also supplies a second endpoint that supplies “metadata” about the current Bible versions supported by the BibleGet engine, and the indices of the chapters and verses for each of these versions. The “metadata” endpoint is https://query.bibleget.io/metadata.php. The parameters to send to the metadata endpoint are:

  • “query”: (required) The “query” parameter can take one of three values:
    • “biblebooks”: This will return data about the list of valid book names and abbreviations in various languages that are currently supported / recognized by the BibleGet engine.
    • “bibleversions”: This will return data about the Bible versions that are currently supported by the BibleGet engine.
    • “versionindex”: This will return data about the indices of chapters and verses for any of the Bible versions currently supported by the BibleGet engine. This value will require a second parameter “versions” other than the “query” parameter.
  • “versions”: (required in case of “versionindex” query request) This indicates for which versions indices data should be returned. This parameter’s value can be either a single version or a comma separated list of versions. The possible values can be retrieved using the “bibleversions” query request.
  • “return”: (optional) The “return” parameter indicates the format in which the structured data should be returned. This parameter takes one of three values: “json”, “xml”, or “html”. If left out, this parameter will default to “json”.

HOW TO QUERY THE ENDPOINT

A query can be sent to the endpoint in a number of ways. Here are some examples:

  • from PHP using CURL
  • from Javascript with an AJAX call (which could also use a PHP script that uses CURL)
  • “src” attribute as an “iframe” element in an HTML page (and using html as the data return type)
  • any language or application that can make a call to a URL can interrogate the service and process the received data. In Java, for example, there are libraries that allow you to make calls to URLs.

Sample query: https://query.bibleget.io/?query=Mt1,1-10;2,2-4&return=html&appid=directurl. Try clicking on this link to see an example of data returned, in this case in HTML format. Then try this one that returns the same data in JSON format, without formatting or page structure: https://query.bibleget.io/?query=Mt1,1-10;2,2-4&return=json&appid=directurl.

You can experiment with the query formulation and requests and response types in the Sandbox Area: Sandbox Area.

CACHE REQUESTS TO THE ENDPOINT

Considering the fact the contents of the responses are not dynamic values but mostly static values (the biblical texts will hardly ever change, only if some error is found and updated in the database), applications that make requests should use some kind of local cache meccanism, especially when the application or plugin is website or blog page that can be opened and consulted by a number of users or by the general public. Keep in mind that without some kind of cache meccanism, the web page will generate a new request to the endpoint every time the page is opened. An inconsiderate implementation without a cache meccanism could easily lead to thousands of useless requests being made to the service, especially when the web page is indexed by search engines. The search engines themselves would wind up generating useless requests to the endpoint just by scraping the page for indexing!

Take for example the WordPress plugin. I have made use of WordPress transients so as to cache the response locally for the requests that are generated by the shortcodes. This way when anyone opens a page in which the request has already been made beforehand, the response stored in the transient will be used instead of generating a new request to the endpoint. This kind of considerate usage will allow this project to survive and be used by more applications. Currently the endpoint engine does a few checks on incoming requests: if too many requests are coming from the same source (a web page for example) for the same query, either a notification will accompany the response inviting to use a cache meccanism or service will be outright denied. If this project continues to grow, it will probably become necessary to register an application and receive an API key that will allow that application to make requests, and usage will be monitored.

Share your thoughts!

This site uses Akismet to reduce spam. Learn how your comment data is processed.