Basa Bali Wiki API (Scraper)

API tidak resmi (unofficial) berbasis Node.js untuk mendapatkan definisi kata dan daftar indeks dari kamus online BASAbaliWiki. API ini dibangun dengan melakukan web scraping secara real-time ke situs sumber.

Fitur Utama

• ✅ Definisi Kata Lengkap: Ambil detail definisi, tingkatan bahasa (sor-singgih), dialek, dan contoh kalimat.
• ✅ Indeks Kata A-Z: Dapatkan daftar kata berdasarkan huruf awal.
• ✅ Arsitektur Bersih: Dibangun dengan pola desain berlapis (Routes, Controllers, Services) untuk kemudahan pemeliharaan.
• ✅ Desain RESTful: Endpoint yang bersih dan intuitif, memisahkan sumber daya kata dan indeks.
• ✅ Penanganan Error: Respons error yang informatif dan konsisten.

⚠️ Peringatan: API ini bergantung pada struktur HTML dari situs dictionary.basabali.org. Jika situs sumber mengubah layout-nya, API ini mungkin akan mengalami kegagalan. Gunakan dengan bijak.

Daftar Isi

• Instalasi
• Menjalankan Proyek
• Dokumentasi Endpoint API
  • Sumber Daya: Kata
  • Sumber Daya: Indeks
• Contoh Respons
  • Respons Sukses (Detail Kata)
  • Respons Sukses (Daftar Indeks)
  • Respons Gagal (404 Not Found)
• Teknologi yang Digunakan
• Struktur Proyek
• Potensi Peningkatan
• Lisensi

Instalasi

Untuk menjalankan proyek ini di lingkungan lokal Anda, ikuti langkah-langkah berikut:

1. Clone repositori ini:

   git clone https://github.com/YudaKusumaID/basa-bali-wiki-api.git
   cd basa-bali-wiki-api

2. Instal dependensi proyek: Gunakan npm atau yarn untuk menginstal semua paket yang dibutuhkan.

   npm install

3. Konfigurasi Lingkungan (Environment): Buat file .env di direktori root proyek dengan menyalin dari contoh .env.example atau buat secara manual.

   # Port untuk menjalankan server
   PORT=8080
   
   # Mode environment: 'development' atau 'production'
   # 'development' akan menampilkan stack trace pada error
   NODE_ENV=development

Menjalankan Proyek

• Mode Development (dengan auto-reload): Mode ini menggunakan nodemon untuk secara otomatis me-restart server setiap kali ada perubahan file.

  npm run dev

• Mode Produksi:

  npm start

Setelah server berjalan, Anda akan melihat pesan di konsol:

Server berjalan di http://localhost:8080

Dokumentasi Endpoint API

Semua endpoint berada di bawah base URL: /api/v1

Sumber Daya: Kata

Endpoint ini digunakan untuk mendapatkan detail informasi dari sebuah kata.

GET /api/v1/kata/:nama

Mengambil detail definisi, tingkatan bahasa, dialek, dan contoh penggunaan untuk sebuah kata.

Parameter:

• nama (string, required): Kata dalam Bahasa Bali yang ingin dicari. Contoh: titiang.

Contoh Penggunaan (cURL):

curl http://localhost:8080/api/v1/kata/titiang

Respons Sukses (200 OK): Mengembalikan objek JSON dengan data lengkap tentang kata tersebut. (Lihat Contoh Respons)

Respons Gagal (404 Not Found): Jika kata tidak ditemukan di kamus. (Lihat Contoh Respons Gagal)

Sumber Daya: Indeks

Endpoint ini digunakan untuk mendapatkan daftar kata yang tersedia di kamus.

GET /api/v1/indeks

Mengambil daftar gabungan dari semua kata di kamus, dari A hingga Z.

⚠️ Catatan Performa: Endpoint ini melakukan 26 permintaan scraping secara bersamaan ke situs sumber. Panggilan pertama mungkin akan lambat. Sangat disarankan untuk mengimplementasikan caching pada API ini.

Contoh Penggunaan (cURL):

curl http://localhost:8080/api/v1/indeks

Respons Sukses (200 OK): Mengembalikan objek JSON yang berisi jumlah total kata dan sebuah array besar berisi semua kata.

GET /api/v1/indeks/:huruf

Mengambil daftar semua kata yang diawali dengan huruf tertentu, dengan dukungan pagination.

• Parameter Path:

  • huruf (string, required): Satu karakter alfabet (A-Z, tidak case-sensitive) untuk memfilter daftar kata.

• Query Parameters (Opsional):

  • page (number): Nomor halaman yang ingin ditampilkan.
    • Default: 1
  • limit (number): Jumlah data per halaman.
    • Default: 20
    • Maksimum: 100

• Contoh Penggunaan (cURL):

  • Halaman pertama (default):

    curl "http://localhost:3000/api/v1/indeks/a"

  • Halaman kedua dengan 10 item per halaman:

    curl "http://localhost:3000/api/v1/indeks/a?page=2&limit=10"

• Respons Sukses (200 OK): Mengembalikan objek JSON yang berisi metadata pagination dan daftar kata untuk halaman tersebut.

Parameter:

• huruf (string, required): Satu karakter alfabet (A-Z, tidak case-sensitive) untuk memfilter daftar kata.

Contoh Penggunaan (cURL):

curl http://localhost:8080/api/v1/indeks/b

Respons Sukses (200 OK): Mengembalikan objek JSON yang berisi daftar kata untuk huruf yang diminta. (Lihat Contoh Respons)

Contoh Respons

Respons Sukses (Detail Kata)

Permintaan: GET /api/v1/kata/titiang

{
    "success": true,
    "message": "Definisi untuk kata 'titiang' berhasil diambil.",
    "data": {
        "word": "Titiang",
        "definitions": [
            { "lang": "en", "text": "first person singular pronouns" },
            { "lang": "en", "text": "I; me (Alus sor)" },
            { "lang": "id", "text": "saya (Alus sor)" },
            { "lang": "id", "text": "kata ganti orang pertama tunggal" }
        ],
        "speechLevels": [
            { "level": "Kasar", "text": "ake; wake; kola" },
            { "level": "Andap", "text": "cang; icang; dewek; gelah" },
            { "level": "Alus sor", "text": "titiang" },
            { "level": "Alus madya", "text": "tiang" }
        ],
        "dialects": [
            { "dialect": "Bali Dataran", "text": "Oke (Buleleng); Oke (Jembrana, Batur); Kola (Nusa Penida)" }
        ],
        "examples": [
            {
                "balinese": "Titiang sampun iriki.",
                "english": "I am already here.",
                "indonesian": "Saya sudah di sini."
            }
        ]
    }
}

Respons Sukses (Daftar Indeks dengan Pagination)

Permintaan: GET /api/v1/indeks/a?page=1&limit=5

{
    "success": true,
    "message": "Daftar kata untuk huruf 'A' berhasil diambil.",
    "pagination": {
        "currentPage": 1,
        "totalPages": 165,
        "limit": 5,
        "totalItems": 822,
        "itemsOnPage": 5
    },
    "data": [
        "A",
        "Aa",
        "Aab",
        "Aad",
        "Aag"
    ]
}

Respons Gagal (404 Not Found)

Permintaan: GET /api/v1/kata/katangawag

{
    "success": false,
    "status": 404,
    "message": "Kata 'katangawag' tidak ditemukan di kamus."
}

Teknologi yang Digunakan

• Node.js - Lingkungan eksekusi JavaScript.
• Express.js - Framework web minimalis untuk Node.js.
• Axios - Klien HTTP berbasis Promise untuk browser dan Node.js.
• Cheerio - Implementasi cepat dan fleksibel dari jQuery Core untuk server.
• Dotenv - Memuat variabel lingkungan dari file .env.
• Nodemon - Utilitas untuk me-restart server secara otomatis saat pengembangan.

Struktur Proyek

Proyek ini menggunakan arsitektur berlapis untuk memisahkan tanggung jawab (Separation of Concerns).

/src
├── api/
│   └── routes/         # Mendefinisikan endpoint API
├── controllers/        # Mengelola alur request-response
├── services/           # Berisi logika bisnis inti (scraping)
├── utils/              # Utilitas pembantu (e.g., kelas Error)
└── app.js              # Entry point aplikasi & konfigurasi Express

Lisensi

Proyek ini dilisensikan di bawah Lisensi MIT. Lihat file LICENSE untuk detail lebih lanjut.