Developer Tools: API
Widget
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 asv2
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 tohttps://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
Response
<?xml version="1.0" encoding="utf-8"?>
<versions>
<version id="AMP">
[...]
</version>
<version id="GNT">
[...]
</version>
<meta>
[...]
</meta>
</versions>
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
Response
<?xml version="1.0" encoding="utf-8"?>
<response>
<versions>
<version id="AMP">
[...]
</version>
<version id="GNT">
[...]
</version>
</versions>
<meta>
[...]
</meta>
</response>
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 atext_preview
element with the first few verses of the passage. Instead it contains atext
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 thepath
element to get the full text. In version 2, the second request is unnecessary. Additionally,passage
elements contain a newcopyright
element and the format of thestart_verse
andend_verse
elements has changed. - The
versions
endpoint includes newlang_name
andlang_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
, andauditid
.
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.