Add hadiths list endpoint with filtering support (#1811)

main.py

@@ -107,6 +107,32 @@ def api_collection_book_chapter(collection_name, bookNumber, chapterId):
     return Chapter.query.filter_by(collection=collection_name, arabicBookID=book_id, babID=chapterId)
 
 
+@app.route("/v1/hadiths", methods=["GET"])
+@paginate_results
+def api_hadiths():
+    query = Hadith.query
+
+    # Apply filters based on query parameters
+    collection = request.args.get("collection")
+    if collection:
+        query = query.filter_by(collection=collection)
+
+    book_number = request.args.get("bookNumber")
+    if book_number:
+        query = query.filter_by(bookNumber=book_number)
+
+    chapter_id = request.args.get("chapterId")
+    if chapter_id:
+        query = query.filter_by(babID=float(chapter_id))
+
+    hadith_number = request.args.get("hadithNumber")
+    if hadith_number:
+        query = query.filter_by(hadithNumber=hadith_number)
+
+    # Order by URN for consistent results
+    return query.order_by(Hadith.englishURN)
+
+
 @app.route("/v1/hadiths/<int:urn>", methods=["GET"])
 @single_resource
 def api_hadith(urn):

spec.v1.yml

@@ -227,6 +227,48 @@ paths:
           required: true
           schema:
             type: string
+  /hadiths:
+    get:
+      summary: Get a list of hadiths
+      description: ""
+      responses:
+        "200":
+          description: Paginated list of hadiths
+          content:
+            application/json:
+              schema:
+                type: object
+                allOf:
+                  - properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Hadith"
+                  - $ref: "#/components/schemas/PaginatedResponse"
+      parameters:
+        - in: query
+          name: collection
+          description: Name of the collection
+          schema:
+            type: string
+        - in: query
+          name: bookNumber
+          description: Number of the book
+          schema:
+            type: string
+        - in: query
+          name: chapterId
+          description: ID of the chapter
+          schema:
+            type: number
+            format: float
+        - in: query
+          name: hadithNumber
+          description: Hadith number
+          schema:
+            type: string
+        - $ref: "#/components/parameters/limit"
+        - $ref: "#/components/parameters/page"
   "/hadiths/{urn}":
     get:
       summary: Get a hadith by its URN