# 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
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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 `NoPagination` for complete dataset retrieval
- Database queries are optimized with `select_related` and `prefetch_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:
```json
{
  "count": <total_records>,
  "results": {
    "<id>": { ...record_data... }
  }
}
```

This format allows for easy lookup by ID and provides total count information.