Endpoint Surah dan Ayah

Ketiga endpoint surah berbagi satu array in-memory. SurahHandler mengambilnya lewat destructuring { data: quran } dari data/quran.json, lalu setiap route mendaftarkan satu static method berbeda bersama middleware caching (api/handlers/surah.js:1¹, api/routes.js:34-38²). Karena data sudah berada di memori proses, handler tidak melakukan I/O per request; seluruh variasi response datang dari pemangkasan field dan pemeriksaan indeks array.

Pola path dan contoh ketiga endpoint juga dipublikasikan oleh route indeks / (api/routes.js:14-32³), dan README mencatat endpoint yang sama beserta contoh /surah/110 dan /surah/2/255 (README.md:43-45⁴).

Peta endpoint

Hanya getAllSurah yang memangkas dua field sekaligus: setiap item disalin dengan spread, lalu verses dan preBismillah dihapus dari salinan itu (api/handlers/surah.js:4-17⁵). getSurah tidak memangkas apa pun; objek quran[surah - 1] dikirim langsung sebagai data (api/handlers/surah.js:19-36⁶). getAyahFromSurah menyusun objek baru { ...checkAyah, surah: dataSurah } sehingga ayah yang diminta berada di level atas dan metadata surahnya berada di data.surah (api/handlers/surah.js:38-68⁷).

Siklus request /surah/{surah}/{ayah}

sequenceDiagram
  autonumber
  participant C as Client
  participant R as api/routes.js
  participant M as caching
  participant H as SurahHandler
  participant D as quran in-memory

  C->>R: GET /surah/18/60
  R->>M: caching(req, res, next)
  alt req.url sudah ada di cache
    M-->>C: 200 dengan body dari cache
  else cache miss
    M->>H: getAyahFromSurah(req, res)
    H->>D: quran[surah - 1]
    alt checkSurah kosong
      H-->>C: 404 Surah ... is not found.
    else surah ditemukan
      H->>D: checkSurah.verses[ayah - 1]
      alt checkAyah kosong
        H-->>C: 404 Ayah ... in surah ... is not found.
      else ayah ditemukan
        H->>H: delete dataSurah.verses
        H-->>C: 200 Success fetching ayah
      end
    end
  end
%% fig: Siklus request ayah dari route sampai 200 atau 404
%% desc: Router meneruskan request ke middleware caching, lalu handler memeriksa indeks surah dan indeks ayah sebelum mengirim response.

Ada dua gerbang pemeriksaan berurutan, dan keduanya memakai pesan berbeda. Gerbang pertama memeriksa checkSurah hasil quran[surah - 1]; bila kosong, response 404 memakai pesan surah. Gerbang kedua memeriksa checkAyah hasil checkSurah.verses[ayah - 1]; bila kosong, response 404 memakai pesan ayah beserta nomor surahnya (api/handlers/surah.js:38-68⁷). Percabangan alt pertama pada diagram berasal dari middleware caching, yang menyimpan body per req.url dan tidak memanggil handler saat entri sudah ada (api/middlewares.js:6-9⁸).

Pemangkasan verses dan preBismillah

graph LR
  Q["quran: data array dari quran.json"] --> H1["getAllSurah"]
  Q --> H2["getSurah"]
  Q --> H3["getAyahFromSurah"]
  H1 --> O1["item tanpa verses dan preBismillah"]
  H2 --> O2["item utuh: verses dan preBismillah terbawa"]
  H3 --> O3["satu ayah + data.surah tanpa verses"]
  O1 --> M1["message: Success fetching all surah."]
  O2 --> M2["message: Success fetching surah."]
  O3 --> M3["message: Success fetching ayah"]
  style Q fill:#336791,color:#fff
  style O1 fill:#8b5cf6,color:#fff
  style O3 fill:#8b5cf6,color:#fff
  style O2 fill:#f59e0b,color:#000
  style M1 fill:#2d7d46,color:#fff
  style M2 fill:#2d7d46,color:#fff
  style M3 fill:#2d7d46,color:#fff
%% fig: Tiga handler membaca satu array quran dengan pemangkasan berbeda
%% desc: Array yang sama dilayani oleh tiga method SurahHandler, masing-masing mengirim bentuk data dan message sukses yang berbeda.

preBismillah tidak selalu objek. Pada surah 1 field itu bernilai null (data/quran.json:6-30⁹), sedangkan pada surah lain berisi text, translation, dan audio (data/quran.json:338-356¹⁰). Asal-usul bentuk ini dibahas di Normalisasi Ayah dan preBismillah; halaman ini hanya mencatat dampaknya pada response. Perhatikan bahwa getAllSurah dan getAyahFromSurah menyalin objek dengan spread sebelum delete, sehingga array quran di memori tidak ikut kehilangan field.

Indeks array dan parameter string

req.params selalu berupa string, dan quran[surah - 1] bergantung pada koersi angka dari string itu. Nilai non-numerik menghasilkan NaN, sehingga quran[NaN] bernilai undefined dan berakhir di 404 Surah "abc" is not found. Tidak ada validasi rentang eksplisit di handler; /surah/0 pun gagal karena quran[-1] kosong (api/handlers/surah.js:19-36⁶). Parameter ayah ditafsirkan sebagai posisi di dalam verses, bukan number.inQuran, jadi /surah/18/60 mengambil verses[59] (api/handlers/surah.js:38-68⁷). Nilai numberOfVerses pada objek surah bisa dipakai klien sebagai batas atas sebelum meminta ayah (data/quran.json:6-30⁹).

Status gagal dan pesan

Pesan itu dirangkai langsung dari req.params, dan body error selalu menyertakan data: {} (api/handlers/surah.js:19-36⁶, api/handlers/surah.js:38-68⁷). Kontrak response secara umum, termasuk bentuk amplop code, status, message, dan data, dibahas di Kontrak Response dan Penanganan Error.

Catatan integrasi

⚠️ Body error ikut masuk cache. Middleware caching membungkus res.send dan menyimpan body apa pun dengan key req.url, lalu mengirim ulang entri itu sebagai 200 (api/middlewares.js:6-9⁸). Request kedua ke /surah/999 karena itu dapat menerima status 200 dengan body 404. Mekanisme lengkapnya ada di Alur Request dan Middleware caching.

⚠️ /surah/{surah} mengirim verses penuh, termasuk tafsir.id.short dan tafsir.id.long untuk setiap ayah (data/quran.json:357-397¹¹). Untuk surah panjang seperti Al-Baqarah response menjadi sangat besar; pakai /surah untuk daftar dan /surah/{surah}/{ayah} untuk satu ayah.

Router juga memasang header Cache-Control bernilai public, max-age=0, s-maxage=86400, stale-while-revalidate untuk semua route, termasuk ketiga endpoint surah (api/routes.js:9-12¹²).