Developer Tools: API

Application Programming Interface (API)

Introduction

The ABS Bible Search API is available via XML or JSON requests served over HTTP using RESTful resources. Accessing Bible passages via the API is a read-only process; you may access this content via HTTP GET requests.

Because the ABS Bible Search API is accessible via HTTP, you may use a regular browser to view all GET requests for the API. If you are using the XML interface, we recommend using Mozilla Firefox or Google Chrome for this, since they will happily render XML in the browser. JSON responses can also be viewed in the browser, but they are harder to read without formatting. For many URLs in the ABS Bible Search web application, you may simply append .xml or .js to the URL to retrieve the corresponding API response for that URL. For example, /eng-GNTD/Gen/1 becomes /eng-GNTD/Gen/1.xml to retrieve the XML version or /eng-GNTD/Gen/1.js to retrieve the JSON version.

Authentication

All requests to the ABS API are authenticated via an API application key. Using a Bible Search account, you can register each of your applications that use the API and you will get a unique authentication key for each fo them. Each application has read-only access to all of the Bible passages available to the API.

If you have not yet registered your API Application, please see the "How do I get access?" section of the Developer Tools: API page. Every request must include your application's API key. If necessary for your development environment, you may pass a dummy password along with your request.

Here is an example of how to use cURL to access our API. (The dummy password “X” is being passed with this request.)

curl -u #{your API token}:X -k https://ga.bibles.org/v2/versions/eng-GNTD.xml

Remember to keep your authentication token private. Anything you can do via the website you can do via the API, so protect your API token as you would protect your username and password for the website. If you ever want to change your API token, go to the details page for your API App and click the "Request a new key" link.

Versioning

Each request to the API can be made with or without a version number. If no version is specified, the current default API version will be used for the response.

The current default API version is version 1.

The version is specified with a /vX/ URL segment at the beginning of any URL. For example, this URL uses the default version:

https://ga.bibles.org/versions/eng-GNTD/books.xml

And this URL uses version 2:

https://ga.bibles.org/v2/versions/eng-GNTD/books.xml

If a version is specified that is out of range (either too high or too low), it will be clamped to the closest valid version.

Making Secure (SSL) Requests

Because every request sends along your authentication token, it is in your best interest to always make secure API requests to keep your token safe. This means using SSL by specifying 'https' as the protocol for your URLs instead of 'http'. You'll notice that all our examples have URLs beginning with 'https://ga.bibles.org/'. Access via non-SSL URLs still works, but is deprecated and not recommended.

Reading (HTTP GET requests)

There are two categories of actions used to read data from the ABS API: list and show. List actions return a collection of records (such as all versions of the Bibles ABS provides) and may sometimes be filtered by certain criteria described in this documentation. Each resource typically offers a single show action to return data about that individual resource (a particular book of a particular Bible version, for example). If a resource has a parent resource (a Version is the parent of a Book, for example), the child resource includes a parent node linking to the canonical URL of its parent. If a resource has sibling resources (e.g. next and previous chapters, if the resource is a Chapter), the resource will include next and previous nodes. A resource may have a next node, a previous node, or both. Sibling resources roll over to the siblings of parents and grandparents if necessary. For example, if a resource is the last chapter in a book, the next node will contain information about the first chapter in the next book.

You may access all list and show actions via GET requests. These are easily performed via either the browser or via command line:

Browser (load this URL in FireFox):

https://#{your API token}:ga.bibles.org/v2/versions/eng-GNTD.xml

Command line (using curl):

curl -u #{your API token}:X -k https://ga.bibles.org/v2/versions/eng-GNTD.xml

If the read request is successful, the XML response will include the status code “200 OK.”

Note: Bible passages are only available via read requests. Write access is not available for Bible passages.

Searching (HTTP GET requests)

Fully automatic searches, where a general query is used and the site figures out the contents of the query, can be done via the search.xml endpoint. If the query looks like a passage search, the endpoint will redirect to the appropriate passage search url. If the query looks like a keyword search, the endpoint will redirect to the appropriate verse keyword search url.

Additionally, the user can specify that a search should only be considered a keyword search via a particular request to the Verses resources.

Errors

Error responses from the server will return a response code in the range 400-499. When appropriate, error responses will contain error messages formatted in either XML or JSON (depending on the requested content type) to explain what caused the error.

Response codes

Successful requests

Successful requests will return HTTP response codes in the 200s.

Record selected, updated, or deleted
HTTP/1.1 200 OK
Record created
HTTP/1.1 201 Created

Unsuccessful requests

Unsuccessful requests will return HTTP response codes in the 400s.

Malformed request

If you submit poorly formed XML or JSON to the API, you will receive this response.

HTTP/1.1 400 Bad Request
Authentication credentials needed
HTTP/1.1 401 Unauthorized
Non-existent route or resource
HTTP/1.1 404 Not Found
Invalid data

When you try to create or update a record with invalid data, you will receive this response.

HTTP/1.1 422 Unprocessable Entity

API conventions

Throughout this documentation, the following conventions are in use:

  • #{text}: Indicates that this text should be replaced by your own data.
  • …: Indicates that a portion of the response has been omitted for brevity and clarity’s sake.
  • Green boxes: indicate that the contained text is part of the request portion of an example.
  • Orange boxes: indicate that the contained text is part of the response portion of an example.