bible_api

If you are hosting bible_api on Dokku and need to rebuild the database (e.g., after a migration or initial setup), follow these steps to create a new database, import the data using the provided Ruby script, and promote the new database to production.

Note: Replace bible_api_2024 with your desired database name and bible-api.com with your actual Dokku app name. Ensure you use the correct environment variable provided by Dokku for the DATABASE_URL during the import step.

# 1. Create and link the new database
dokku mysql:create bible_api_2024
dokku mysql:link bible_api_2024 bible-api.com

# 2. Enter the app container and run the import script
dokku enter bible-api.com
# Inside the container, use the Dokku-provided MySQL URL
DATABASE_URL="$DOKKU_MYSQL_AQUA_URL" ruby import.rb
exit

# 3. Promote the new database to production
dokku mysql:promote bible_api_2024 bible-api.com

# 4. Cleanup old databases (optional)
dokku mysql:unlink bible_api_2023 bible-api.com
dokku mysql:stop bible_api_2023
dokku mysql:destroy bible_api_2023

To self-host the bible_api, you need a Linux server with Ruby, Redis, and MySQL (or MariaDB) installed.

1. Clone and Prepare

git clone https://github.com/seven1m/bible_api
cd bible_api
git submodule update --init

2. Install Dependencies

gem install bundler
bundle config --local deployment true
bundle install

3. Database Setup and Data Import

First, create the MySQL database and user, then set the required environment variables before running the import script:

mysql -uroot -e "create database bible_api; grant all on bible_api.* to user@localhost identified by 'password';"
export DATABASE_URL="mysql2://user:password@localhost/bible_api"
export REDIS_URL="redis://localhost:6379"
bundle exec ruby import.rb

4. Run the Application

For testing, run:

bundle exec ruby app.rb

For production, it is recommended to use Passenger.

The Rack::AbuseMiddleware is a middleware used to prevent abuse by blocking IP addresses that trigger too many 404 (Not Found) errors within a specific time window. It requires a redis instance to track request counts and block status.

Configuration Options

When initializing the middleware, you can provide an options hash with the following keys:

Behavior

• IP Detection: Uses the HTTP_X_FORWARDED_FOR header (taking the first IP in the list) or REMOTE_ADDR.
• Blocking: If an IP exceeds the :limit of 404 errors within the :window, it is flagged in Redis and will receive a 403 Forbidden response for the duration of :block_time.

Rack::AbuseMiddleware.new(app, {
  redis: Redis.new,
  limit: 10,
  window: 30,
  block_time: 3600
})

The API returns a JSON object with the following structure:

• reference: The Bible reference string (e.g., "John 3:16").
• verses: An array of verse objects. Each object contains:
  • book_id: The abbreviated book name (e.g., "JHN").
  • book_name: The full book name (e.g., "John").
  • chapter: The chapter number.
  • verse: The verse number.
  • text: The verse text content.
• text: A concatenated string of all requested verse texts.
• translation_id: The ID of the translation used (e.g., "web").
• translation_name: The name of the translation (e.g., "World English Bible").
• translation_note: Notes regarding the translation's copyright status.

{
  "reference": "John 3:16",
  "verses": [
    {
      "book_id": "JHN",
      "book_name": "John",
      "chapter": 3,
      "verse": 16,
      "text": "\nFor God so loved the world...\n\n"
    }
  ],
  "text": "\nFor God so loved the world...\n\n",
  "translation_id": "web",
  "translation_name": "World English Bible",
  "translation_note": "Public Domain"
}

The primary endpoint for fetching specific verses or ranges is /:ref. The ref is a string representing the Bible reference (e.g., John 3:16 or John 3:16-18).

Features:

• Ranges: Supports ranges like John 3:16-18.
• Chapter Limits: You cannot fetch more than one whole chapter at once (e.g., John 3:16-4:1 is allowed, but John 3:16-5:1 is blocked to prevent abuse).
• Verse Numbers: If you pass the query parameter verse_numbers=true, the text field in the response will include the verse numbers in parentheses (e.g., (1) In the beginning...).
• Single Chapter Matching: By default, a reference like Jude 1 refers to a single verse. If you want it to match the whole chapter, you must pass the query parameter single_chapter_book_matching=indifferent.

GET /John+3:16-18
GET /John+3:16?verse_numbers=true
GET /Jude+1?single_chapter_book_matching=indifferent

Response format:
{
  "reference": "John 3:16-18",
  "verses": [
    { "book_id": "JHN", "book": "John", "chapter": 3, "verse": 16, "text": "For God so loved..." }
  ],
  "text": "For God so loved...",
  "translation_id": "WEB",
  "translation_name": "World English Bible",
  "translation_note": "..."
}