church-api/HYMNARIUM_API_DOCUMENTATION.md

Adventist Hymnarium API Documentation

Overview

The Church API includes a comprehensive hymnal system supporting both the 1985 Seventh-day Adventist Hymnal and the 1941 Church Hymnal. The system provides intelligent search capabilities, complete hymn content, thematic organization, and responsive readings.

Database Structure

Migration & Data Standardization

• Migration Date: August 27, 2025
• Total Hymns: 1,398 hymns (695 from 1985 + 703 from 1941)
• Data Source: SQLite hymnarium.db migrated to PostgreSQL
• Format Standardization: Both hymnals now use consistent numbered verse formatting (1., 2., 3., etc.)

The 1941 hymnal content was automatically converted from its original format to match the 1985 numbered verse structure for consistency.

Database Schema

Hymnals Table

- id: UUID (primary key)
- name: VARCHAR(100) - Display name
- code: VARCHAR(50) - Unique identifier (sda-1985, sda-1941) 
- description: TEXT
- year: INTEGER
- language: VARCHAR(10) - Default 'en'
- is_active: BOOLEAN

Hymns Table

- id: UUID (primary key)
- hymnal_id: UUID (foreign key to hymnals)
- number: INTEGER - Hymn number within that hymnal
- title: VARCHAR(255)
- content: TEXT - Full hymn text with standardized verse numbering
- is_favorite: BOOLEAN
- UNIQUE(hymnal_id, number)

Additional Tables

• thematic_lists: Theme categories (Worship, Trinity, etc.)
• thematic_ambits: Hymn number ranges within themes
• responsive_readings: Numbered 696-920 (from 1985 hymnal)

API Endpoints

Base URL

http://localhost:3002/api

Hymnals

List All Hymnals

GET /hymnals

Response:

{
  "success": true,
  "data": [
    {
      "id": "39484599-c028-4c19-8c9d-2b174f13efa6",
      "name": "Seventh-day Adventist Hymnal",
      "code": "sda-1985",
      "description": "The current SDA Church Hymnal published in 1985",
      "year": 1985,
      "language": "en",
      "is_active": true
    },
    {
      "id": "698045d8-231c-4bd5-8fef-8af0deab8cb4", 
      "name": "Church Hymnal",
      "code": "sda-1941",
      "description": "The older SDA Church Hymnal published in 1941",
      "year": 1941,
      "language": "en",
      "is_active": true
    }
  ]
}

Get Hymnal by Code

GET /hymnals/code/{code}

Example: GET /hymnals/code/sda-1985

Hymns

List All Hymns from a Specific Hymnal

GET /hymns/search?hymnal={hymnal_code}&per_page=1000

Example: GET /hymns/search?hymnal=sda-1985&per_page=1000

This returns all 695 hymns from the 1985 hymnal or all 703 hymns from the 1941 hymnal.

Get Specific Hymn

GET /hymns/{hymnal_code}/{number}

Example: GET /hymns/sda-1985/1

Response:

{
  "success": true,
  "data": {
    "id": "35ab3b49-e49b-470b-a104-c2632089af49",
    "hymnal_id": "39484599-c028-4c19-8c9d-2b174f13efa6",
    "hymnal_name": "Seventh-day Adventist Hymnal",
    "hymnal_code": "sda-1985",
    "hymnal_year": 1985,
    "number": 1,
    "title": "Praise to the Lord",
    "content": "1.\nPraise to the Lord, the Almighty, the King of creation!\nO my soul, praise Him, for He is thy health and salvation!\n...",
    "is_favorite": false
  }
}

Intelligent Search System

Search Hymns

GET /hymns/search?q={search_term}&hymnal={hymnal_code}&per_page={limit}

Parameters:

• q: Search term (required for text searches)
• hymnal: Filter by hymnal code (sda-1985 or sda-1941) - RECOMMENDED
• per_page: Results limit (default: 20)
• page: Page number for pagination

Search Features & Scoring

The search system uses intelligent scoring (higher scores = better matches):

Search Types Supported:

1. Hymn Numbers: 123, hymn 123, no. 123, number 123
2. Exact Titles: Amazing Grace
3. Multi-word Phrases: friend jesus → finds "What a Friend We Have in Jesus"
4. Partial Titles: praise lord → finds "Praise to the Lord"
5. Lyrics Content: how sweet the sound → finds Amazing Grace
6. Any Word Order: jesus friend and friend jesus both work

Scoring System:

• 1600 points: Exact hymn number match
• 1500 points: Exact title match
• 1200 points: Title starts with search term
• 800 points: Title contains exact phrase
• 700 points: All search words found in title (multi-word bonus)
• 650 points: 3+ search words found in title
• 600 points: First line contains phrase
• 400 points: Any search word in title
• 300 points: Content contains exact phrase
• 200 points: Multi-word match in content
• 100 points: Any search word in content

Search Examples

Single Hymnal Search (Recommended):

GET /hymns/search?q=amazing%20grace&hymnal=sda-1985

Multi-word Search:

GET /hymns/search?q=friend%20jesus&hymnal=sda-1985

Number Search:

GET /hymns/search?q=123&hymnal=sda-1941

Cross-Hymnal Search (if needed):

GET /hymns/search?q=amazing%20grace

Thematic Organization

Get Themes for a Hymnal

GET /hymnals/code/{hymnal_code}/themes

Example: GET /hymnals/code/sda-1985/themes

Returns thematic lists with their hymn number ranges (ambits).

Responsive Readings

List Responsive Readings

GET /responsive-readings?per_page=225

Get Specific Responsive Reading

GET /responsive-readings/{number}

Example: GET /responsive-readings/696

Note: Responsive readings are numbered 696-920 (from the 1985 hymnal section).

Frontend Integration Guide

Recommended Usage Pattern

1. Hymnal Selection: Let users choose between sda-1985 or sda-1941
2. Scoped Searches: Always include hymnal={selected_hymnal} parameter
3. Search URL Pattern: /api/hymns/search?q={searchTerm}&hymnal={selectedHymnal}

Example Frontend Logic

const selectedHymnal = 'sda-1985'; // or 'sda-1941'
const searchTerm = 'friend jesus';

const searchUrl = `/api/hymns/search?q=${encodeURIComponent(searchTerm)}&hymnal=${selectedHymnal}&per_page=20`;

// This returns only hymns from the selected hymnal with intelligent scoring

Content Format

All hymn content uses standardized formatting:

1.
[First verse content]

2. 
[Second verse content]

3.
[Third verse content]

Both 1985 and 1941 hymnals now use this consistent format.

Technical Implementation

Search Intelligence

The backend handles all search complexity including:

• Multi-word term splitting
• Phrase detection
• Word order independence
• Relevance scoring
• Performance optimization

Database Optimizations

• Full-text search indexes on titles and content
• Optimized queries with CTEs for scoring
• Proper foreign key relationships
• Pagination support

Error Handling

All endpoints return standardized responses:

{
  "success": boolean,
  "data": any,
  "message": string | null
}

Migration Details

Data Processing

1. Source: SQLite hymnarium.db with 1,398 hymns
2. Processing: Python migration script with intelligent format conversion
3. Standardization: 1941 hymnal verses automatically numbered to match 1985 format
4. Validation: All hymns migrated successfully with proper relationships

Migration Script Location

/opt/rtsda/church-api/migrate_hymnal_data.py

Performance Notes

• Search Performance: Optimized with PostgreSQL indexes and scoring CTEs
• Database Size: ~1,400 hymns with full content searchable
• Response Times: Sub-second search responses
• Scalability: Ready for additional hymnals or languages

Development Notes

Code Organization

• Search Logic: /src/services/hymnal_search.rs
• Main Service: /src/services/hymnal.rs
• Handlers: /src/handlers/hymnal.rs
• Models: Defined in /src/models.rs

Future Enhancements

• Fuzzy matching for typos
• Additional hymnal languages
• Advanced search filters
• Bookmark/favorites system
• Audio integration support

---

Last Updated: August 27, 2025
API Version: 1.0
Database: PostgreSQL with 1,398 standardized hymns