Back to Bible Search

Developer Tools: API

This documentation describes version 2 of the API. If you are still using version 1, you can view the version 1 documentation for this page.

Widget

Create

Highlighter - Beta

API

Migrating your apps to the Bible Search API version 2

After several years of stability, the Bible Search API is getting an upgrade. We've made improvements to both the data that is returned by API requests and the structure of the responses. We're also officially supporting a JSON interface, in addition to the XML interface.

To make it easier for you to migrate your apps, both versions 1 and 2 of the API will be available in parallel for several months. During this time, you can request a specific version of the API by adding either /v1/ or /v2/ segments to the URLs of your API calls. For example, if the default version URL for a resource is https://bibles.org/versions.xml, you can specify the version with one of these two URLs: https://bibles.org/v1/versions.xml or https://bibles.org/v2/versions.xml.

Currently, if no version is specified, version 1 of the API will be used. In a couple of months, the default version will be switched to v2, so requests that don't specify a version will get version 2, but clients specifying v1 will still get version 1. Finally, a while later the v1 API will be disabled completely and even requests that specify v1 will recieve version v2 responses.

Here is the timeline for the version change:

March 27, 2013 Version 2 of the API is usable with an explicit version specification in the URL. The default version (when none is explicitly specified) is still v1.
June 1, 2013 The default version switches from v1 to v2. The v1 interface is still available when specified explicitly.
July 1, 2013 The v1 interface is disabled and removed completely. Requests that specify v1 will be silently handled as v2 requests.

Changes Overview

There have been several major changes to the way the API works. The following things have all changed:

Authentication

With version 2 of the API, there has been a shift in the context of authentication tokens. In version 1, API tokens were issued on a per-user basis. In version 2, there is a new concept of API Apps and each app has its own token. In order to migrate your existing apps, you will need to create a new API Application for each website or application that uses the API. Then, change the API Token in each website or application from the v1 user token to the appropriate v2 application token.

Example: You currently have two websites that use version 1 of the Bible Search API, www.excitingbiblestories.com and www.amazingchristianhistory.com. You have a single API token that both sites use when sending requests to the Bible Search API.

These are the steps you need to take to update your API authentication to the new scheme:

Go to the My Applications page, logging in if necessary.
For each of the two websites, click "Create an application" and fill out the site's details.
Once the application has been created, you will see both websites listed on the My Applications page.
Edit each website and wherever the old API key is stored, replace it with the site-specific "Private API Key.
Change all of the API URLs in your sites' source code to include the v2 specifier. For example, if you were previously sending a request to https://bibles.org/versions/GNT/books.xml, change it to https://bibles.org/v2/versions/GNT/books.xml.

After finishing these steps, your websites will be able to successfully send requests to version 2 of the API.

JSON Response Format

With version 2, the Bible Search API fully supports JSON format requests and responses in addition to the XML format. If you were using the previously undocumented JSON interface, significant changes have been made to clean up the JSON responses and make them easier to work with. All of the endpoint documentation now contains both XML and JSON examples. Be sure you're reading the v2 documentation and not the v1 documentation in order to make use of the better JSON interface.

Response Structure

A major change has been made to the overall structure of the XML and JSON responses. Previously, the top-level element of every response had the type of the response data. For example, requests to the /versions endpoint would return responses that looked like this:

Example (v1 API):

Request

XML

JSON

GET https://bibles.org/versions.xml

GET https://bibles.org/versions.js

Response

<?xml version="1.0" encoding="utf-8"?>
<versions>
  <version id="AMP">
    [...]
  </version>
  <version id="GNT">
    [...]
  </version>
  <meta>
    [...]
  </meta>
</versions>

{
    "versions": {
        "0": {
            "version": {
                "version": "AMP",
                [...]
            }
        },
        "1": {
            "version": {
                "version": "GNT",
                [...]
            }
        },
        "meta": {
            [...]
        }
    }
}

As you can see, the top-level element is a <versions> element and the <meta> element is one of its children. In version 2 of the Bible Search API, there is a new top-level <response> element which contains the <versions> and <meta> elements:

Example (v2 API):

Request

XML

JSON

GET https://bibles.org/v2/versions.xml

GET https://bibles.org/v2/versions.js

Response

<?xml version="1.0" encoding="utf-8"?>
<response>
  <versions>
    <version id="AMP">
      [...]
    </version>
    <version id="GNT">
      [...]
    </version>
  </versions>
  <meta>
      [...]
  </meta>
</response>

{
    "response": {
        "versions": [
            {
                "id": "AMP",
                [...]
            },
            {
                "id": "GNT",
                [...]
            },
        ],
        "meta": {
            [...]
        }
    }
}

This change will make it easier for your client code to separate the data collection and meta elements.

Response Data

There have been a few changes to the data returned from specific API endpoints. If your code depends on the old response data, it will need to be updated to deal with the new responses.

The /passages endpoint no long returns a text_preview element with the first few verses of the passage. Instead it contains a text element with the full text of the passage. With version 1 of the API, you would have to send a second request to the URL in the path element to get the full text. In version 2, the second request is unnecessary. Additionally, passage elements contain a new copyright element and the format of the start_verse and end_verse elements has changed.
The versions endpoint includes new lang_name and lang_name_eng which contain the localized name of the version's language and the English name of the version's language. Also, four version properties have been removed from these responses: active, active_api, orderindex, and auditid.

User Data

In version 2 of the API, access to user-specific data has been removed. This means that access to User, Note, and Tagging data is no longer available. These pieces of data are no longer readable or writable via the API. The desktop website must be used to view and edit this information.