Ringkasan Proyek

quran-api adalah REST API untuk Al-Qur'an yang menyajikan daftar surah, satu surah, satu ayat dalam surah, dan satu juz. Seluruh data dibaca dari berkas JSON yang di-require ke memori proses, sehingga tidak ada database yang di-query saat request dilayani. README menyebut teknik ini sebagai indexed querying dengan waktu akses 0(1). README.md:26-27

Berkas data/quran.json menyimpan metadata berkas (license, source, audioEdition) dan array data yang memuat seluruh surah. data/quran.json:1-5 Array itu dihasilkan oleh crawler/script.js, yang mengulang for (let i = 1; i <= 114; i++) untuk 114 surah lalu menulis hasilnya ke ./data/quran.json. crawler/script.js:182-191 crawler/script.js:196-204

Peta modul

graph TD
  vercel["vercel.json<br/>@vercel/node"] --> server["api/server.js"]
  heroku["app.json<br/>heroku-18"] --> server
  server --> routes["api/routes.js"]
  routes --> mw["api/middlewares.js<br/>caching"]
  routes --> surahHandler["api/handlers/surah.js"]
  routes --> juzHandler["api/handlers/juz.js"]
  surahHandler --> quranData["data/quran.json"]
  juzHandler --> juzLib["api/lib/juz.js"]
  juzLib --> quranData
  juzLib --> juzData["data/juz.json"]
  crawlerScript["crawler/script.js"] --> quranData
  crawlerHelpers["crawler/helpers.js<br/>sleep"] --> crawlerScript
  config["config.js + .env"] --> crawlerScript
  style quranData fill:#336791,color:#fff
  style juzData fill:#336791,color:#fff
  style mw fill:#8b5cf6,color:#fff
  style juzLib fill:#8b5cf6,color:#fff
  style config fill:#f59e0b,color:#000
  style routes fill:#2d7d46,color:#fff
  style surahHandler fill:#2d7d46,color:#fff
  style juzHandler fill:#2d7d46,color:#fff
  style crawlerHelpers fill:#f59e0b,color:#000
  %% fig: Peta modul quran-api
  %% desc: Server Express melayani request lewat routes, handler membaca berkas JSON di data/, sementara crawler menulis ulang data/quran.json dari sumber eksternal.

Fig. 1: Peta modul quran-apiServer Express melayani request lewat routes, handler membaca berkas JSON di data/, sementara crawler menulis ulang data/quran.json dari sumber eksternal.

Tiga direktori membentuk repository ini. api/ memuat server Express beserta handler-nya, crawler/ memuat pipeline pengambilan data, dan data/ memuat dua berkas JSON yang dibaca saat runtime.

Modul	Peran	Rujukan
`api/server.js`	Memasang `cors()`, `express.json()`, lalu `routes`; listen pada `process.env.PORT` atau `3000`	api/server.js:1-18
`api/routes.js`	Mendefinisikan `Router`, header `Cache-Control`, empat rute data, dan fallback 404	api/routes.js:1-47
`api/middlewares.js`	Menyimpan `response` ke objek `cache` dengan kunci `req.url`	api/middlewares.js:1-21
`api/handlers/surah.js`	`SurahHandler` dengan `getAllSurah`, `getSurah`, `getAyahFromSurah`	api/handlers/surah.js:1-71
`api/handlers/juz.js`	`JuzHandler.getJuz` yang memanggil `juzData`	api/handlers/juz.js:1-26
`api/lib/juz.js`	Fungsi `juzData` yang merakit ayat dari rentang `start` dan `end`	api/lib/juz.js:1-49
`data/quran.json`	Sumber seluruh surah dan ayat	data/quran.json:1-5
`data/juz.json`	Daftar rentang `start` dan `end` per juz	data/juz.json:1-4
`crawler/script.js`	Mengambil data dari `SOURCE_API_BASEURL`, merakit objek, menulis `data/quran.json`	crawler/script.js:12-18
`crawler/helpers.js`	Helper `sleep` untuk membatasi `timeout` saat fetch	crawler/helpers.js:1-10
`config.js`	Membaca `MONGODB_URI`, `SOURCE_API_BASEURL`, `SOURCE_API_BASEURL_2` dari `.env`	config.js:1-11

Fakta utama

Aspek	Nilai	Rujukan
Nama dan versi paket	`quran-api` versi `1.0.0`, `main` di `api/server.js`	package.json:2-4
Perintah npm	`build`, `start`, `dev`, `crawl`	package.json:9-14
Dependencies runtime	`cors`, `dotenv`, `express`	package.json:15-19
devDependencies	`eslint`, `isomorphic-fetch`, `nodemon`	package.json:20-24
Jumlah surah pada pipeline crawler	114, dari loop `i <= 114`	crawler/script.js:182-191
Header cache response	`public, max-age=0, s-maxage=86400, stale-while-revalidate`	api/routes.js:9-12
Target deploy	`@vercel/node` dengan sumber `api/server.js`, atau Heroku `heroku-18`	vercel.json:1-11 app.json:1-13

Endpoint yang tersedia

Empat rute data didaftarkan di api/routes.js, masing-masing memakai middleware caching. README menjelaskan keempatnya sebagai daftar surah, surah spesifik, ayat dalam surah, dan juz. README.md:42-46 api/routes.js:14-38

Rute	Handler	Rujukan
`GET /surah`	`SurahHandler.getAllSurah`	api/routes.js:34
`GET /surah/:surah`	`SurahHandler.getSurah`	api/routes.js:36
`GET /surah/:surah/:ayah`	`SurahHandler.getAyahFromSurah`	api/routes.js:37
`GET /juz/:juz`	`JuzHandler.getJuz`	api/routes.js:38
`ALL *`	Fallback 404 dengan pesan `Resource "..." is not found.`	api/routes.js:40-45

⚠️ Live API di https://api.quran.gading.dev sudah dibatasi rate limiter 10req/5min/address dan 150req/5min for the whole server, jadi jangan dijadikan dependensi berkelanjutan. README menyarankan deploy sendiri. README.md:8-11

⚠️ crawler/script.js menulis ulang ./data/quran.json secara penuh setelah mengambil 114 surah. Jalankan npm run crawl hanya ketika data sumber memang ingin diganti. crawler/script.js:196-204

Cakupan halaman lain

Mekanisme caching dan urutan middleware dibahas di Alur Request dan Middleware caching. Detail setiap rute ada di Referensi Endpoint, Endpoint Surah dan Ayah, dan Endpoint Juz. Bentuk quran.json dan juz.json dijelaskan di Model Data quran.json dan juz.json, sedangkan perhitungan rentangnya ada di Komputasi Rentang Juz. Pipeline pengambilan data diuraikan di Crawler: Pipeline Pengambilan Data, dan langkah menjalankan server ada di Konfigurasi, Menjalankan Lokal, dan Deployment.