Developers

SERVICE ENDPOINT

The BibleGet I/O Project makes a service "Endpoint" available for applications, 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.

ENDPOINT URL

The main url for requests is http://query.bibleget.io/(which is the same as http://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 ENPOINT

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 http://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: http://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: http://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: Area Sandbox.

Share your thoughts!

%d bloggers like this: