Introduction

The ABS BibleSearch API is available via XML requests served over HTTP using RESTful resources. Accessing Bible passages via API is a read-only process; you may access this content via HTTP GET requests. To interact with user-specific features like accounts, tags, and notes, you may read and write to the API using all four HTTP verbs (GET/POST/PUT/DELETE).

Because the ABS BibleSearch API is accessible via HTTP, you may use a regular browser to view all GET requests for the API. We recommend using Firefox for this, since it will happily render XML in the browser. For many URLs in the ABS BibleSearch application, you may simply append .xml to the URL to retrieve the corresponding API response for that URL. For example, /versions/kjv/books becomes /versions/kjv/books.xml to retrieve the XML version.

You may also retrieve JSON responses from the ABS BibleSearch application by appending .js to the request URL. For example, /versions/kjv/books becomes /versions/kjv/books.js to retrieve the JSON version.

Authentication

All requests to the ABS API are authenticated via an existing ABS user account – you do not need a special API user account to access the API. All users have full read access to all Bible passages. For user-specific content such as account information, tags, and notes, users have full read and write access, but only to their own content.

API Authentication is done via an authentication token, which you’ll find on your account settings page in the ABS BibleSearch application. Every request must include your 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://biblesearch.americanbible.org/versions/GNT.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, simply change your account password via the account settings page, and your API token will be changed as well.

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://biblesearch.americanbible.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}:biblesearch.americanbible.org/versions/GNT.xml

Command line (using curl):

curl -u #{your API token}:X -k https://biblesearch.americanbible.org/versions/GNT.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.

Writing (HTTP POST and PUT requests)

You may use the ABS API to create and update content that you, yourself, have created. This includes account information, tags, and notes. To perform these write requests, you will need to send an XML request to the ABS API along with the relevant HTTP verb for your action. Because of these requirements, it is not easy to interact with the ABS API using your browser to send these write requests. Instead, we recommend you use a command line tool like curl to play around with this portion of the ABS API interface.

To create new resources via the ABS API, send the resource encoded as XML or JSON. Be sure to also send the correct Content-type header with your request. This will be either “Content-type: application/xml” for XML requests or “Content-type: application/javascript” for JSON requests. Data should be sent to the ABS API as the raw POST or PUT body.

Examples:

To create a new tag via the ABS API, do this:

curl -u #{your API token}:X -k -X POST -H 'Content-Type: application/xml' \
-d '<tagging><tag><name>peace</name></tag><references><reference><start>GNT:John.3.18</start><end>GNT:John.3.18</end></reference></references></tagging>' \
https://biblesearch.americanbible.org/user/taggings.xml

Successful creations respond with the status code “201 Created.” The response will also include the URL of the resource in the location header and the complete resource, formatted as XML. It’s helpful to use the returned resources attributes (especially the id attribute) to interact with the resource in subsequent requests.

You may update resources you have created by performing an HTTP PUT request. The resource attributes you pass with the request (as XML) will replace the attributes on file for that resource.

A sample tag update request:

curl -u #{your API token}:X -k -X PUT -H 'Content-Type: application/xml' \
-d '<tagging><tag><name>peace</name></tag></tagging>' https://biblesearch.americanbible.org/taggings/12.xml

Successful update requests return the response code “200 OK.”

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.

Deleting (HTTP DELETE requests)

You may delete content that you, yourself, have created by sending an HTTP DELETE request (in this example, to delete a tag):

curl -u #{your API TOKEN}:X -k -X DELETE https://biblesearch.americanbible.org/tags/5.xml

Note: The content-type header is not needed for DELETE requests, since you are not sending any XML to the ABS API.

Successful update requests return the response code “200 OK” and the updated object in the response body.

Successful delete requests return the response code “200 OK” and an empty response body.

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.