User Flows

How to Navigate the API

As the primary method for documenting the Bible Brain API, we offer a Postman collection containing the API endpoints, organized by function. See the note in Core Concepts about how to install and configure Postman. Once Postman is installed, you can review the collection by importing from here: Example Workflows.

Once you have the “Example Workflows” collection configured, you’ll see a series of folders:

    - General information on Languages, Countries, Alphabets, Bible books
    - How to find the right Bible (and accompanying Filesets)
    - Once I have a Bible/Fileset, how do I access content?
    - OpenAPI

Each folder contains requests which can assist you in planning your application. 

For example, the General Information folder can provide information on Languages available in a Country or translations available for a Bible. There are also endpoints to provide information on alphabets and numeral systems. 

The next folder,  How to find the right Bible (and accompanying Filesets), provides a set of filters for language code, content type (eg text, audio, video). It also provides general information on Bible book order, publisher  information, and specifics about what content types are available for a particular Bible. Once you narrow your search, the key to retrieving content is the Fileset identifier. Review the Core Concepts page for details on how to work with the Fileset id. 

The third folder contains requests necessary for retrieving Bible content and required copyright information. You will notice that almost all content can be retrieved from a single endpoint, as long as you know the FilesetId. 

The final folder contains an endpoint for retrieving the OpenAPI 3.0 definition of the Bible Brain API. This is used to generate the reference documentation. But if you would like to use a different OpenAPI-compliant tool, the endpoint will provide an up-to-date version of the definition in json format.

‍

Questions to ask as you design your application:

1. Do you have a specific Bible and Version you want to use, or will you allow the end user to select one? If you intend to provide the user with options, you can query the API to provide the content for those options.
2. Do you plan to deliver text only, or would you prefer to deliver audio and/or video? If you deliver both text and audio, and would like a “karaoke”-style synchronization option, you can access the Audio Timings endpoints to find accurate starting times for each verse.
3. Will your users be accessing audio content from a slow network? If yes, you may want to consider using the 16kbps audio encoded via Ogg/Opus. Tests indicate for Bible content (eg spoken word and some background music) the audio quality is comparable to 64kbps mp3.