Catatan Harian Mas Andri

Silahkan digunakan dengan bijaksana

back

Membangun API Al-Quran Tanpa Server dengan Google Apps Script

23 Maret 2025 || 14:45:15 WIB || ClassyID

Di era digital seperti sekarang, kebutuhan akan akses Al-Quran dalam format digital semakin meningkat. Banyak pengembang Muslim yang ingin membangun aplikasi atau website Al-Quran, namun seringkali terkendala dengan biaya infrastruktur server dan database. Artikel ini akan membahas bagaimana membangun API Al-Quran yang andal menggunakan Google Apps Script dan Google Spreadsheet sebagai database, tanpa memerlukan biaya server yang mahal.

Mengapa Google Apps Script?

Google Apps Script menawarkan beberapa keuntungan yang signifikan untuk proyek semacam ini:

  1. Tanpa Biaya Server: Google Apps Script berjalan di infrastruktur Google, sehingga Anda tidak perlu mengeluarkan biaya untuk server.

  2. Integrasi dengan Google Spreadsheet: Memungkinkan penggunaan spreadsheet sebagai database yang mudah dikelola.

  3. Kuota yang Mencukupi: Untuk aplikasi skala kecil hingga menengah, kuota Google Apps Script sudah lebih dari cukup.

  4. Kemudahan Pengelolaan: Data dapat diperbarui langsung melalui antarmuka spreadsheet yang familiar.

Struktur Data Al-Quran

API ini menggunakan dua sheet utama dalam Google Spreadsheet:

Sheet surahQuran

Sheet ini berisi informasi tentang setiap surah dalam Al-Quran, dengan kolom utama:

Sheet ayatQuran

Sheet ini berisi seluruh ayat Al-Quran dengan kolom:

Fitur Utama API

API yang dibangun menyediakan beberapa endpoint utama:

1. Mengakses Daftar Surah

?action=getAllSurah

Endpoint ini mengembalikan daftar lengkap 114 surah dalam Al-Quran beserta metadata terkait. Ini berguna untuk membangun daftar navigasi di aplikasi Al-Quran.

2. Mengakses Satu Surah Lengkap

?action=getSurah&number=1

Endpoint ini mengembalikan informasi lengkap tentang surah tertentu, termasuk semua ayat di dalamnya. Parameter number menentukan nomor surah yang diminta.

3. Mengakses Ayat Spesifik

?action=getAyat&surah=1&ayat=1

Endpoint ini mengembalikan satu ayat spesifik berdasarkan nomor surah dan ayat.

4. Fitur Pencarian

?action=search&q=keyword

Endpoint ini memungkinkan pencarian ayat berdasarkan kata kunci, yang bisa berupa teks Arab, latin, atau terjemahan.

5. Akses Berdasarkan Juz

?action=getJuz&number=1

Endpoint ini mengembalikan semua ayat dalam juz tertentu, berguna untuk aplikasi yang mengorganisasi Al-Quran berdasarkan juz.

6. Akses Berdasarkan Halaman Mushaf

?action=getPage&number=1

Endpoint ini mengembalikan semua ayat dalam halaman mushaf tertentu, menyesuaikan dengan format halaman mushaf standar.

7. Akses Audio

?action=getAudio&surah=1&ayat=1&qari=default

Endpoint ini mengembalikan URL audio untuk ayat tertentu, dengan opsi memilih qari.

Implementasi Teknis

Struktur Kode

Kode Google Apps Script untuk API ini diorganisasi dengan beberapa fungsi utama:

  1. doGet(): Fungsi utama yang menangani permintaan HTTP GET dan merutekan ke fungsi yang sesuai.

  2. Fungsi Endpoint: Satu fungsi untuk setiap endpoint API (getAllSurah, getSurah, getAyat, dll.).

  3. Fungsi Utilitas: Fungsi pendukung seperti caching, parsing data, dll.

Caching untuk Performa

Salah satu tantangan dalam menggunakan Google Spreadsheet sebagai database adalah performa. Untuk mengatasi hal ini, API mengimplementasikan sistem caching yang menyimpan hasil query selama 6 jam:

function getCachedSheet(sheetName) {
  const cache = CacheService.getScriptCache();
  const cacheKey = `sheet_${sheetName}`;
  const cachedData = cache.get(cacheKey);
  
  if (cachedData !== null) {
    return JSON.parse(cachedData);
  }
  
  // Query data jika tidak ada di cache
  const spreadsheet = SpreadsheetApp.openById(SPREADSHEET_ID);
  const sheet = spreadsheet.getSheetByName(sheetName);
  const data = sheet.getDataRange().getValues();
  
  // Simpan ke cache selama 6 jam
  cache.put(cacheKey, JSON.stringify(data), 21600);
  
  return data;
}

Pelacakan Penggunaan (Analytics)

API juga dilengkapi dengan sistem pelacakan penggunaan sederhana yang menyimpan data tentang endpoint mana yang paling sering digunakan:

function trackAnalytics(endpoint, params = {}) {
  try {
    // Dapatkan tanggal saat ini dalam format YYYY-MM-DD
    const today = new Date();
    const dateStr = Utilities.formatDate(today, 'GMT', 'yyyy-MM-dd');
    
    // Kunci untuk menyimpan data analytics harian
    const analyticsKey = `analytics_${dateStr}`;
    
    // Dapatkan data analytics yang sudah ada, atau buat objek baru
    let analyticsData = {};
    const existingData = PROPERTY_STORE.getProperty(analyticsKey);
    
    if (existingData) {
      analyticsData = JSON.parse(existingData);
    }
    
    // Tambahkan hit untuk endpoint
    if (!analyticsData[endpoint]) {
      analyticsData[endpoint] = { count: 0, params: {} };
    }
    analyticsData[endpoint].count++;
    
    // Simpan data kembali ke property store
    PROPERTY_STORE.setProperty(analyticsKey, JSON.stringify(analyticsData));
  } catch (error) {
    console.error('Error tracking analytics:', error);
  }
}

Cara Deployment

Berikut adalah langkah-langkah untuk men-deploy API Al-Quran dengan Google Apps Script:

  1. Siapkan Google Spreadsheet:

    • Buat spreadsheet baru di Google Drive
    • Buat dua sheet: surahQuran dan ayatQuran
    • Impor data surah dan ayat ke sheet masing-masing

  2. Buat Google Apps Script:

    • Dari menu Google Spreadsheet, pilih Extensions > Apps Script
    • Salin kode API ke editor script
    • Ganti SPREADSHEET_ID dengan ID spreadsheet Anda

  3. Deploy sebagai Web App:

    • Dari editor Apps Script, pilih Deploy > New deployment
    • Pilih jenis "Web app"
    • Set "Execute as" ke "Me"
    • Set "Who has access" ke "Anyone"
    • Klik "Deploy"

  4. Gunakan URL Web App:

    • Setelah deploy berhasil, Anda akan mendapatkan URL web app
    • Gunakan URL ini sebagai basis untuk API Anda

Kasus Penggunaan

API ini dapat digunakan untuk berbagai jenis aplikasi, seperti:

  1. Website Al-Quran: Membuat website untuk membaca Al-Quran dengan terjemahan dan audio.

  2. Aplikasi Mobile: Mengintegrasikan API ke dalam aplikasi mobile untuk akses Al-Quran offline.

  3. Bot Telegram/WhatsApp: Membuat bot yang mengirimkan ayat Al-Quran berdasarkan permintaan.

  4. Widget untuk Website/Blog: Menampilkan ayat Al-Quran random di website.

  5. Aplikasi Pembelajaran: Membuat aplikasi untuk belajar membaca atau menghafal Al-Quran.

Batasan dan Solusi

Meskipun menawarkan banyak keuntungan, pendekatan ini juga memiliki beberapa batasan:

  1. Kuota API: Google Apps Script memiliki batasan jumlah eksekusi harian. Untuk aplikasi dengan traffic tinggi, ini bisa menjadi masalah.

    Solusi: Implementasikan caching di sisi client dan kurangi frekuensi permintaan.

  2. Kecepatan: Akses ke Google Spreadsheet bisa lebih lambat dibandingkan database tradisional.

    Solusi: Gunakan caching agresif dan optimalkan struktur data.

  3. Ukuran Data: Google Spreadsheet memiliki batasan pada jumlah baris dan kolom.

    Solusi: Untuk data yang sangat besar, pertimbangkan untuk memecah data ke beberapa spreadsheet.

Kesimpulan

Membangun API Al-Quran dengan Google Apps Script dan Google Spreadsheet menawarkan solusi yang terjangkau dan mudah dikelola untuk pengembang individu atau organisasi kecil. Meskipun memiliki beberapa batasan, pendekatan ini sangat cocok untuk banyak kasus penggunaan dan dapat menjadi alternatif yang baik untuk solusi berbasis server tradisional.

Yang terpenting, proyek semacam ini memungkinkan lebih banyak Muslim untuk berkontribusi dalam membuat Al-Quran lebih mudah diakses dalam format digital, sehingga lebih banyak orang dapat membaca dan mempelajari kitab suci ini di era teknologi.

Kode sumber lengkap untuk API ini tersedia di GITHUB, dan Anda dipersilakan untuk menggunakannya, memodifikasinya, atau berkontribusi untuk pengembangannya lebih lanjut.

Artikel ini ditulis sebagai panduan teknis dan juga inspirasi bagi pengembang Muslim yang ingin berkontribusi dalam menyebarkan Al-Quran melalui teknologi.