Referensi Endpoint

Halaman ini memetakan seluruh route yang terdaftar di satu Router Express pada api/routes.js. Router itu dipasang ke aplikasi tanpa prefix lewat server.use(routes), sehingga setiap path yang didefinisikan di dalamnya dipakai apa adanya sebagai URL publik (api/server.js:11-14¹).

Peta Router

graph TD
  server["express() di api/server.js"] --> cors["cors()"]
  cors --> json["express.json()"]
  json --> router["Router dari api/routes.js"]
  router --> header["router.use — header Cache-Control"]
  header --> root["GET /"]
  router --> surahList["GET /surah"]
  router --> surahOne["GET /surah/:surah"]
  router --> surahAyah["GET /surah/:surah/:ayah"]
  router --> juzRoute["GET /juz/:juz"]
  router --> fallback["router.all '*' — 404"]
  surahList --> getAllSurah["SurahHandler.getAllSurah"]
  surahOne --> getSurah["SurahHandler.getSurah"]
  surahAyah --> getAyah["SurahHandler.getAyahFromSurah"]
  juzRoute --> getJuz["JuzHandler.getJuz"]
  style server fill:#f59e0b,color:#000
  style cors fill:#f59e0b,color:#000
  style json fill:#f59e0b,color:#000
  style router fill:#f59e0b,color:#000
  style header fill:#8b5cf6,color:#fff
  style getAllSurah fill:#2d7d46,color:#fff
  style getSurah fill:#2d7d46,color:#fff
  style getAyah fill:#2d7d46,color:#fff
  style getJuz fill:#8b5cf6,color:#fff
  style fallback fill:#dc2626,color:#fff
%% fig: Pohon route dari aplikasi Express ke setiap handler
%% desc: Satu Router di api/routes.js menjadi induk dari endpoint root, empat route data, dan fallback 404; warna menandai konfigurasi, jalur berhasil, data turunan, dan kegagalan.

Router dibentuk dengan Router() dan seluruh response yang melewatinya lebih dulu melewati satu middleware router.use yang menetapkan header Cache-Control: public, max-age=0, s-maxage=86400, stale-while-revalidate (api/routes.js:9-12²). Node header pada diagram mewakili middleware itu, dan node getJuz diberi warna data turunan karena handler juz menghitung rentang ayat alih-alih membacanya langsung.

Daftar Route

Keempat route data didaftarkan berurutan pada satu blok yang sama, masing-masing dengan middleware caching sebelum handler-nya (api/routes.js:34-38⁷). Contoh path pada tabel di atas adalah contoh yang juga ditulis sendiri oleh endpoint root, yaitu /surah/18, /surah/18/60, dan /juz/30 (api/routes.js:14-32⁸). Empat endpoint itu juga didokumentasikan di README.md:42-46⁹.

Parameter Path

Tidak ada route yang memakai query string. Seluruh masukan datang dari parameter path, dan cara pembacaannya berbeda antara handler surah dan handler juz.

Nilai req.params selalu berupa string, tetapi aritmetika surah - 1 dan ayah - 1 tetap bekerja karena JavaScript mengonversinya saat pengurangan. Handler juz memilih konversi eksplisit lewat parseInt(juz) sebelum memanggil juzData (api/handlers/juz.js:4-23⁶). Untuk isi data yang dikembalikan tiap route, lihat Endpoint Surah dan Ayah serta Endpoint Juz.

Endpoint Root sebagai Metadata

GET / tidak membaca berkas data. Handler-nya hanya mengirim objek statis berisi pola path yang tersedia, nama maintaner, dan URL source (api/routes.js:14-32⁸).

Penulisan spesificSurah mengikuti nama field aslinya di kode, jadi kunci itu harus dikutip persis seperti di atas. Endpoint root juga tidak memakai middleware caching, sehingga response-nya tidak masuk ke cache di memori.

Fallback 404

Route terakhir adalah router.all('*', ...) yang membalas status 404 dengan code: 404, status: 'Not Found.', dan message berformat Resource "${req.url}" is not found. (api/routes.js:40-45¹⁰).

⚠️ Fallback ini harus tetap berada di akhir berkas. Express mencocokkan route sesuai urutan pendaftaran, sehingga route GET yang ditulis setelah router.all('*') tidak akan pernah tercapai.

Response fallback juga tidak melewati middleware caching (api/middlewares.js:3-17¹¹), jadi pemanggilan path yang salah tetap dieksekusi ulang setiap kali dan tidak disimpan di cache. Rincian bentuk response dan aturan errornya dibahas di Kontrak Response dan Penanganan Error, sedangkan daur hidup middleware caching dijelaskan di Alur Request dan Middleware caching.