You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
19 KiB
19 KiB
Hadis Sync API Endpoints Documentation
This document provides comprehensive examples of all sync endpoints in the Hadis API. These endpoints are designed for offline mobile applications and return complete datasets in optimized formats.
Overview
The sync endpoints provide complete data synchronization for offline use. They return all data at once (no pagination) and are optimized with select_related and prefetch_related for performance.
Base URL
https://api.example.com/api/hadis/
1. Sync Sects
Endpoint: GET /sync/sects/
Purpose: Get all active sects grouped by sect type (Shia/Sunni)
Response Structure
{
"shia": [
{
"id": 1,
"title": "Shia Hadith Collections",
"description": "Primary collections of Shia hadith",
"source_types": ["quran", "hadith"]
}
],
"sunni": [
{
"id": 2,
"title": "Sunni Hadith Collections",
"description": "Primary collections of Sunni hadith",
"source_types": ["hadith"]
}
]
}
2. Sync Categories Tree
Endpoint: GET /sync/categories/tree/
Purpose: Get complete hierarchical category tree grouped by sect type with enhanced child information
Response Structure
{
"count": 12,
"results": {
"shia": {
"sects": {
"1": {
"id": 1,
"sect_type": "shia",
"title": "Shia Hadith Collections",
"description": "Collections of Shia hadith",
"order": 1
}
},
"categories": {
"quran": [
{
"id": 1,
"name": "Tafsir",
"hadis_count": 150,
"has_hadis": false,
"order": 1,
"xmind_file": "http://example.com/media/xmind/tafsir.xmind",
"has_xmind_file": true,
"children": [
{
"id": 2,
"name": "Surah Al-Fatiha",
"hadis_count": 25,
"has_hadis": true,
"order": 1,
"father_category": {
"id": 1,
"name": "Tafsir",
"sect_id": 1,
"sect_type": "shia",
"source_type": "quran"
},
"hadis_details": [
{
"id": 1,
"title": "The Opening",
"title_narrator": "From Abu Hurairah",
"text": "Actions are but by intention...",
"translation": "Actions are but by intention...",
"share_link": "http://example.com/hadis/1"
},
{
"id": 2,
"title": "Prayer Times",
"title_narrator": "From Abdullah ibn Masud",
"text": "The five daily prayers...",
"translation": "The five daily prayers...",
"share_link": "http://example.com/hadis/2"
}
],
"children": []
},
{
"id": 3,
"name": "Surah Al-Baqarah",
"hadis_count": 125,
"has_hadis": false,
"order": 2,
"father_category": {
"id": 1,
"name": "Tafsir",
"sect_id": 1,
"sect_type": "shia",
"source_type": "quran"
},
"children": [
{
"id": 4,
"name": "Verses 1-50",
"hadis_count": 75,
"has_hadis": true,
"father_category": {
"id": 3,
"name": "Surah Al-Baqarah",
"sect_id": 1,
"sect_type": "shia",
"source_type": "quran"
},
"hadis_details": [
{
"id": 5,
"title": "About Prayer",
"title_narrator": "From Ali ibn Abi Talib",
"text": "Prayer is the pillar of religion...",
"translation": "Prayer is the pillar of religion...",
"share_link": "http://example.com/hadis/5"
}
]
}
]
}
]
}
],
"hadith": []
}
},
"sunni": {
"sects": {
"2": {
"id": 2,
"sect_type": "sunni",
"title": "Sunni Hadith Collections",
"description": "Collections of Sunni hadith",
"order": 2
}
},
"categories": {
"hadith": [
{
"id": 10,
"name": "Sahih al-Bukhari",
"hadis_count": 2500,
"has_hadis": true,
"hadis_details": [
{
"id": 100,
"title": "The Beginning of Revelation",
"title_narrator": "From Aisha",
"text": "The first revelation came to Prophet Muhammad...",
"translation": "The first revelation came to Prophet Muhammad...",
"share_link": "http://example.com/hadis/100"
},
{
"id": 101,
"title": "Prayer in the Mosque",
"title_narrator": "From Umar ibn Khattab",
"text": "The reward of prayer in congregation...",
"translation": "The reward of prayer in congregation...",
"share_link": "http://example.com/hadis/101"
}
],
"children": []
},
{
"id": 11,
"name": "Sahih Muslim",
"hadis_count": 2200,
"has_hadis": false,
"children": [
{
"id": 12,
"name": "Book of Faith",
"hadis_count": 150,
"has_hadis": true,
"father_category": {
"id": 11,
"name": "Sahih Muslim",
"sect_id": 2,
"sect_type": "sunni",
"source_type": "hadith"
},
"hadis_details": [
{
"id": 200,
"title": "Faith and Actions",
"title_narrator": "From Abu Hurairah",
"text": "Faith consists of more than sixty branches...",
"translation": "Faith consists of more than sixty branches...",
"share_link": "http://example.com/hadis/200"
}
]
}
]
}
]
}
}
}
}
3. Sync Hadis
Endpoint: GET /sync/hadis/
Purpose: Get all hadis data for offline synchronization
Response Structure
{
"count": 1500,
"results": {
"1": {
"id": 1,
"number": 1,
"category_id": 2,
"title": "The Opening",
"title_narrator": "From Abu Hurairah",
"text": "Actions are but by intention...",
"description": "This hadith emphasizes the importance of intention in all actions...",
"translations": {
"en": "Actions are but by intention...",
"ar": "إنما الأعمال بالنيات...",
"fa": "اعمال به نیت است..."
},
"explanation": "This hadith emphasizes the importance of intention in all actions...",
"address": "Sahih al-Bukhari, Book of Revelation",
"hadis_status": {
"id": 1,
"title": "Sahih",
"color": "green"
},
"hadis_status_text": "Authentic",
"share_link": "http://example.com/hadis/1",
"tags": [
{"id": 1, "title": "Intention"},
{"id": 2, "title": "Actions"}
],
"links": {
"audio": "http://example.com/audio/hadis1.mp3",
"video": "http://example.com/video/hadis1.mp4"
},
"transmitters": [
{
"id": 1,
"order": 1,
"is_gap": false,
"narrator_layer": "sahaba",
"transmitter": {
"id": 1,
"full_name": "Abu Hurairah",
"birth_year_hijri": 18,
"death_year_hijri": 59,
"madhhab": "sunni",
"description": "One of the most prolific narrators of hadith",
"reliability": "very_reliable"
}
}
],
"references": [
{
"id": 1,
"title": "Sahih al-Bukhari",
"images": [
{
"id": 1,
"image": "http://example.com/media/books/bukhari_cover.jpg",
"order": 1,
"description": "Front cover of Sahih al-Bukhari"
}
],
"authors": [
{
"id": 1,
"name": "Muhammad ibn Isma'il al-Bukhari"
}
],
"description": "The most authentic collection of hadith compiled by Imam Bukhari"
}
],
"corrections": [
{
"id": 1,
"title": "Translation Correction",
"description": "Corrected translation for better accuracy",
"translation": {
"en": "Actions are judged by intentions...",
"ar": "إنما الأعمال بالنيات...",
"fa": "اعمال به نیت ها قضاوت می شود..."
}
}
]
},
"2": {
"id": 2,
"number": 2,
"category_id": 3,
"title": "Five Pillars of Islam",
"title_narrator": "From Abdullah ibn Umar",
"text": "Islam is built on five pillars...",
"translations": {
"en": "Islam is built on five pillars...",
"ar": "بني الإسلام على خمس...",
"fa": "اسلام بر پنج پایه استوار است..."
},
"explanation": "This hadith outlines the fundamental practices of Islam...",
"address": "Sahih al-Bukhari, Book of Faith",
"hadis_status": {
"id": 1,
"title": "Sahih",
"color": "green"
},
"hadis_status_text": "Authentic",
"share_link": "http://example.com/hadis/2",
"tags": [
{"id": 3, "title": "Pillars of Islam"},
{"id": 4, "title": "Faith"}
],
"links": {
"audio": "http://example.com/audio/hadis2.mp3"
}
}
}
}
4. Sync Narrators
Endpoint: GET /sync/narrators/
Purpose: Get all transmitter (narrator) data with biographical information and scholarly opinions
Response Structure
{
"count": 200,
"results": {
"1": {
"id": 1,
"full_name": "Abu Daud Sulaiman ibn al-Ash'ath al-Azdi al-Sijistani",
"biographical": {
"personal_info": {
"full_name": "Abu Daud Sulaiman ibn al-Ash'ath al-Azdi al-Sijistani",
"kunya": "Abu Daud",
"known_as": "Imam Abu Daud",
"nickname": "Al-Sijistani"
},
"dates": {
"birth_year_hijri": 202,
"death_year_hijri": 275,
"age_at_death": 73
},
"locations": {
"origin": "Sijistan (modern Sistan)",
"lived_in": "Basra, Baghdad",
"died_in": "Basra"
},
"religious_profile": {
"reliability": "very_reliable",
"madhhab": "shafii",
"in_sahih_muslim": true,
"in_sahih_bukhari": false
},
"description": "One of the six canonical hadith collectors. Known for his compilation 'Sunan Abu Daud'.",
"thumbnail": "http://example.com/media/transmitters/abu_daud.jpg"
},
"scholars_opinions": [
{
"id": 1,
"scholar_name": "Imam al-Nawawi",
"opinion_text": "Abu Daud is reliable and trustworthy in his transmissions. His collection is one of the six authentic books.",
"status": "confirmed",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
},
{
"id": 2,
"scholar_name": "Ibn Kathir",
"opinion_text": "Abu Daud was meticulous in his research and only included authentic hadith in his collection.",
"status": "confirmed",
"created_at": "2024-01-16T14:20:00Z",
"updated_at": "2024-01-16T14:20:00Z"
}
]
},
"2": {
"id": 2,
"full_name": "Muhammad ibn Isma'il al-Bukhari",
"biographical": {
"personal_info": {
"full_name": "Muhammad ibn Isma'il al-Bukhari",
"kunya": "Abu Abdullah",
"known_as": "Imam al-Bukhari",
"nickname": "The Collector"
},
"dates": {
"birth_year_hijri": 194,
"death_year_hijri": 256,
"age_at_death": 62
},
"locations": {
"origin": "Bukhara (modern Uzbekistan)",
"lived_in": "Bukhara, Nishapur, Baghdad",
"died_in": "Khartank, near Bukhara"
},
"religious_profile": {
"reliability": "very_reliable",
"madhhab": "hanafi",
"in_sahih_muslim": true,
"in_sahih_bukhari": true
},
"description": "The compiler of Sahih al-Bukhari, considered the most authentic hadith collection by Muslims.",
"thumbnail": "http://example.com/media/transmitters/bukhari.jpg"
},
"scholars_opinions": [
{
"id": 3,
"scholar_name": "Imam Muslim",
"opinion_text": "Al-Bukhari is the most knowledgeable person regarding the conditions of narrators and the defects of hadith.",
"status": "confirmed",
"created_at": "2024-01-17T09:15:00Z",
"updated_at": "2024-01-17T09:15:00Z"
},
{
"id": 4,
"scholar_name": "Ibn Hajar al-Asqalani",
"opinion_text": "The hadith of al-Bukhari are the most authentic after the Quran.",
"status": "confirmed",
"created_at": "2024-01-18T11:45:00Z",
"updated_at": "2024-01-18T11:45:00Z"
}
]
}
}
}
5. Sync References
Endpoint: GET /sync/references/
Purpose: Get all book reference data with basic information, detailed publication info, and related hadises
Response Structure
{
"count": 50,
"results": {
"1": {
"id": 1,
"title": "Sahih al-Bukhari",
"basic_info": {
"title": "Sahih al-Bukhari",
"authors": [
{
"id": 1,
"name": "Muhammad ibn Isma'il al-Bukhari"
}
],
"rating": 5.0,
"description": "The most authentic collection of hadith compiled by Imam Bukhari. Contains over 7000 hadith with complete chains of narration.",
"volume": "9 volumes"
},
"information": {
"language": "Arabic",
"isbn": "978-1234567890",
"year_of_publication": "846",
"number_of_pages": 4200,
"volume_info": "9 volumes",
"rating": 5.0
},
"hadis": [
{
"id": 1,
"title": "The Opening",
"title_narrator": "From Abu Hurairah",
"text": "Actions are but by intention...",
"translation": "Actions are but by intention...",
"share_link": "http://example.com/hadis/1"
},
{
"id": 2,
"title": "Five Pillars of Islam",
"title_narrator": "From Abdullah ibn Umar",
"text": "Islam is built on five pillars...",
"translation": "Islam is built on five pillars...",
"share_link": "http://example.com/hadis/2"
},
{
"id": 100,
"title": "The Beginning of Revelation",
"title_narrator": "From Aisha",
"text": "The first revelation came to Prophet Muhammad...",
"translation": "The first revelation came to Prophet Muhammad...",
"share_link": "http://example.com/hadis/100"
}
]
},
"2": {
"id": 2,
"title": "Sahih Muslim",
"basic_info": {
"title": "Sahih Muslim",
"authors": [
{
"id": 2,
"name": "Muslim ibn al-Hajjaj al-Naysaburi"
}
],
"rating": 4.9,
"description": "Second most authentic hadith collection, compiled by Imam Muslim. Known for its strict criteria for authenticity.",
"volume": "8 volumes"
},
"information": {
"language": "Arabic",
"isbn": "978-0987654321",
"year_of_publication": "875",
"number_of_pages": 3800,
"volume_info": "8 volumes",
"rating": 4.9
},
"hadis": [
{
"id": 3,
"title": "Faith and Actions",
"title_narrator": "From Abu Hurairah",
"text": "Faith consists of more than sixty branches...",
"translation": "Faith consists of more than sixty branches...",
"share_link": "http://example.com/hadis/3"
},
{
"id": 4,
"title": "Purification",
"title_narrator": "From Abu Hurairah",
"text": "The key to prayer is purification...",
"translation": "The key to prayer is purification...",
"share_link": "http://example.com/hadis/4"
}
]
},
"3": {
"id": 3,
"title": "Tafsir Ibn Kathir",
"basic_info": {
"title": "Tafsir Ibn Kathir",
"authors": [
{
"id": 3,
"name": "Ibn Kathir"
}
],
"rating": 4.8,
"description": "Comprehensive tafsir (exegesis) of the Quran, combining hadith and scholarly opinions.",
"volume": "4 volumes"
},
"information": {
"language": "Arabic",
"isbn": "978-1122334455",
"year_of_publication": "1370",
"number_of_pages": 2800,
"volume_info": "4 volumes",
"rating": 4.8
},
"hadis": [
{
"id": 5,
"title": "Quranic Interpretation",
"title_narrator": "From Ibn Abbas",
"text": "The Quran should be interpreted in light of the Prophet's explanations...",
"translation": "The Quran should be interpreted in light of the Prophet's explanations...",
"share_link": "http://example.com/hadis/5"
}
]
}
}
}
Usage Notes
Performance Optimizations
- All sync endpoints use
NoPaginationfor complete dataset retrieval - Database queries are optimized with
select_relatedandprefetch_related - Related data is prefetched to avoid N+1 query problems
Data Relationships
- Categories Tree: Hierarchical structure with father category references and embedded hadis details
- Hadis: Include full translation dictionaries and metadata
- Narrators: Biographical data grouped with scholarly opinions
- References: Publication details with embedded related hadis
Offline Synchronization
- Designed for mobile apps requiring complete offline datasets
- Structured for efficient client-side caching and updates
- Includes all necessary related data to minimize API calls
Response Format
All sync endpoints return:
{
"count": <total_records>,
"results": {
"<id>": { ...record_data... }
}
}
This format allows for easy lookup by ID and provides total count information.