🕌 Open Hadith Data API

A comprehensive RESTful API for accessing Islamic Hadith collections from nine major sources, including the Six Books (Al-Kutub Al-Sittah). Features full Arabic text support, advanced search capabilities, and a modern management dashboard.

📋 Features

🔍 Comprehensive Hadith Access

62,174 Hadiths from 9 major Islamic collections
Dual text versions: With and without Arabic diacritics
Collection-specific filtering and pagination
Advanced search with relevance scoring
Full Arabic text support with UTF-8 encoding

🔐 Secure Authentication

Google OAuth 2.0 integration
JWT-based session management
Role-based access control (Admin/User)
API token management with custom permissions

📊 Management Dashboard

Modern responsive UI with Arabic support
Real-time statistics and usage analytics
Token management with CRUD operations
Interactive API testing interface

⚡ High Performance

In-memory caching for fast data access
Efficient indexing algorithms
Rate limiting and security headers
RESTful design with comprehensive endpoints

📚 Collections Included

Collection	Arabic Name	ID
Sahih Al-Bukhari	صحيح البخاري	`sahih_al_bukhari`
Sahih Muslim	صحيح مسلم	`sahih_muslim`
Sunan Abu-Dawud	سنن أبي داود	`sunan_abu_dawud`
Sunan Al-Tirmidhi	سنن الترمذي	`sunan_al_tirmidhi`
Sunan Al-Nasai	سنن النسائي	`sunan_al_nasai`
Sunan Ibn-Maja	سنن ابن ماجه	`sunan_ibn_maja`
Maliks Muwataa	موطأ مالك	`maliks_muwataa`
Sunan Al-Darimi	سنن الدارمي	`sunan_al_darimi`
Musnad Ahmad Ibn-Hanbal	مسند أحمد بن حنبل	`musnad_ahmad_ibn_hanbal`

🚀 Quick Start

Prerequisites

Node.js v18 or higher
npm v8 or higher
Google OAuth credentials (for authentication)

Installation

Clone the repository

git clone https://github.com/your-username/Open-Hadith-Data.git
cd Open-Hadith-Data

Install dependencies
```
npm install
```

Environment setup

cp .env.example .env
# Edit .env with your configuration

Start development server
```
npm run dev
```
Access the application
- API Server: http://localhost:3000
- Documentation: http://localhost:3000/docs/
- Dashboard: http://localhost:3000/dashboard.html
- API Tester: http://localhost:3000/test.html

☁️ Deployment

Deploy to Vercel

Prepare for deployment

# Make sure all dependencies are installed
npm install

Deploy using Vercel CLI

# Install Vercel CLI if not already installed
npm install -g vercel

# Deploy to Vercel
vercel --prod

Configure environment variables in Vercel dashboard

Go to your project settings in Vercel

Add the following environment variables:

NODE_ENV=production
JWT_SECRET=your-production-jwt-secret
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=https://your-domain.vercel.app/auth/google/callback

Deploy to Netlify

Deploy using Netlify CLI

# Install Netlify CLI if not already installed
npm install -g netlify-cli

# Deploy to Netlify
netlify deploy --prod

Configure environment variables in Netlify dashboard
- Go to your site settings in Netlify
- Add the environment variables in the "Environment" section

🔧 Configuration

Environment Variables

Create a .env file in the root directory:

# Server Configuration
NODE_ENV=development
HOST=0.0.0.0
PORT=3000
LOG_LEVEL=info

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRES_IN=24h

# Google OAuth 2.0
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/google/callback

# Rate Limiting
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW=1 minute

# Admin Configuration
ADMIN_EMAILS=admin@example.com,your-email@gmail.com

Google OAuth Setup

Go to Google Cloud Console
Create a new project or select existing
Enable Google+ API
Create OAuth 2.0 credentials
Add http://localhost:3000/auth/google/callback to authorized redirect URIs for local development
For production deployment, also add your domain URL (e.g., https://your-domain.vercel.app/auth/google/callback)
Copy Client ID and Secret to your environment variables

📖 API Documentation

Base URL

http://localhost:3000/api/v1

Authentication

Include your API token in requests:

# Header method
curl -H "X-API-Key: your-api-token" http://localhost:3000/api/v1/collections

# Query parameter method  
curl http://localhost:3000/api/v1/collections?api_key=your-api-token

Core Endpoints

Collections

# Get all collections
GET /api/v1/collections

# Get specific collection
GET /api/v1/collections/{collectionId}

# Get hadiths from collection
GET /api/v1/collections/{collectionId}/hadiths?limit=20&offset=0

# Get specific hadith
GET /api/v1/collections/{collectionId}/hadiths/{hadithId}

Search

# Search hadiths
GET /api/v1/search?q=الصلاة&limit=10

# Search suggestions
GET /api/v1/search/suggestions?q=الصلاة&limit=5

# Advanced search
POST /api/v1/search/advanced
Content-Type: application/json
{
  "query": "الصلاة",
  "collections": ["sahih_al_bukhari"],
  "fileTypes": ["regular"]
}

Statistics

# Get overall statistics
GET /api/v1/stats

# Get collection statistics
GET /api/v1/stats/collections/{collectionId}

# Get text distribution
GET /api/v1/stats/distribution

Response Format

{
  "hadiths": [
    {
      "id": "1",
      "text": "حديث النبي صلى الله عليه وسلم",
      "collectionId": "sahih_al_bukhari",
      "collectionName": "Sahih Al-Bukhari",
      "fileType": "regular"
    }
  ],
  "pagination": {
    "total": 1000,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

🎛️ Dashboard Usage

Login Options

Google OAuth: Click "Login with Google" (recommended)
Demo Account: Use admin@example.com / admin123

Features

📊 Overview: View API statistics and usage metrics
🔑 Token Management: Create, edit, and delete API tokens
⚡ Quick Actions: Fast access to common operations
📱 Responsive Design: Works on desktop and mobile

API Token Management

Create Token: Set name, permissions, and rate limits
Configure Permissions: Read, Write, Admin access levels
Monitor Usage: Track requests and performance
Manage Tokens: Update settings or revoke access

🛠️ Development

Scripts

# Development with auto-restart
npm run dev

# Production start
npm start

# Run tests
npm test

# Watch tests
npm run test:watch

Project Structure

Open-Hadith-Data/
├── server/                 # Backend server code
│   ├── index.js           # Main server file
│   ├── plugins/           # Fastify plugins
│   │   ├── dataLoader.js  # Data management
│   │   └── storage.js     # User/token storage
│   ├── routes/            # API route handlers
│   │   ├── api.js         # Main API routes
│   │   ├── auth.js        # Authentication
│   │   ├── collections.js # Collection endpoints
│   │   ├── search.js      # Search endpoints
│   │   ├── stats.js       # Statistics endpoints
│   │   └── health.js      # Health checks
│   ├── public/            # Static files
│   │   ├── index.html     # API documentation
│   │   ├── dashboard.html # Management dashboard
│   │   └── test.html      # API testing interface
│   └── data/              # Storage directory
├── data/                  # Hadith JSON data
├── scripts/               # Utility scripts
├── .env.example           # Environment template
├── package.json           # Dependencies and scripts
├── CHANGELOG.md           # Version history
└── README.md              # This file

Adding New Features

Create feature branch
Implement changes with tests
Update documentation
Submit pull request

🧪 Testing

API Testing

Use the built-in test interface at /test.html or use curl:

# Test health endpoint
curl http://localhost:3000/health

# Test collections
curl http://localhost:3000/api/v1/collections

# Test search (Arabic)
curl "http://localhost:3000/api/v1/search?q=الصلاة"

Authentication Testing

# Login
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"admin123"}'

# Check status
curl http://localhost:3000/auth/status?sessionId=your-session-id

🔒 Security

Built-in Security Features

JWT Authentication with configurable expiration
Rate Limiting (100 requests/minute by default)
CORS Protection with configurable origins
Security Headers via Helmet middleware
Input Validation and sanitization
Role-based Access Control

Best Practices

Use HTTPS in production
Rotate JWT secrets regularly
Monitor API usage patterns
Implement proper logging
Regular security audits

📈 Performance

Optimization Features

In-memory caching of hadith data (124K+ records)
Efficient indexing for O(1) collection access
Search optimization with relevance scoring
Pagination to handle large result sets
Lazy loading where applicable

Monitoring

Built-in health checks (/health, /health/detailed)
Request/response logging with Pino
Performance metrics in dashboard
Error tracking and reporting

🌍 Deployment

Production Setup

Environment Configuration

NODE_ENV=production
HOST=0.0.0.0
PORT=3000

Process Management

# Using PM2
npm install -g pm2
pm2 start server/index.js --name "hadith-api"

# Using Docker (optional)
docker build -t hadith-api .
docker run -p 3000:3000 hadith-api

Reverse Proxy (Nginx example)

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Update documentation
Submit a pull request

Code Standards

Follow existing code style
Use meaningful commit messages
Add JSDoc comments for functions
Ensure tests pass
Update changelog for significant changes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Islamic Scholars for the compilation and preservation of Hadith collections
Open Source Community for the amazing tools and frameworks
Arabic Text Processing Community for UTF-8 and RTL support guidance
Contributors who help improve and maintain this project
Muhammad Hashim for his early work on Hadith csv files -- Checkout His GitHub

📞 Support

Documentation: Visit /docs/ for comprehensive API documentation
Issues: Report bugs on GitHub Issues
Discussions: Join our GitHub Discussions
Email: Contact the maintainers at [nuzlilatief@gmail.com]

Built with ❤️ for the Islamic developer community

"Seek knowledge from the cradle to the grave" - Prophet Muhammad (ﷺ)

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github		.github
data		data
docs		docs
netlify/functions		netlify/functions
public		public
schema		schema
scripts		scripts
server		server
.env.example		.env.example
.gitignore		.gitignore
.node-version		.node-version
.vercelignore		.vercelignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh
netlify.toml		netlify.toml
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js
vercel.json		vercel.json

License

foozio/Open-Hadith-Data

Folders and files

Latest commit

History

Repository files navigation