Kamus Banjar API

Tujuan dari proyek ini adalah membuat API untuk kamus Bahasa Banjar-Indonesia, yang memberikan pengguna kemampuan untuk menerjemahkan kata dari Bahasa Banjar ke Bahasa Indonesia. Penjelasan secara teori tentang bahasa Banjar silakan merujuk ke halaman wiki.

Baca dengan bahasa lain: English.

Prasyarat

Proyek ini dibangun menggunakan Go version 1.22.2, dan diharapkan untuk dikembangkan menggunakan versi Golang yang serupa untuk mendapatkan hasil sesuai harapan.

Variabel Lingkungan

Variabel	Default	Deskripsi
PORT	:8001	Port server
MYSQL_DSN	—	MySQL DSN. Wajib untuk mengaktifkan autentikasi, komunitas, kontribusi, dan endpoint admin. Tanpa ini, hanya endpoint kamus publik yang aktif.
JWT_SECRET	—	Rahasia JWT (min. 32 karakter). Wajib bila MYSQL_DSN diset.
JWT_ACCESS_TTL	15m	Masa berlaku access token (format Go duration, contoh: 15m, 1h)
JWT_REFRESH_TTL	168h	Masa berlaku refresh token (format Go duration, contoh: 168h, 7d)
ADMIN_EMAIL	—	Email untuk akun admin awal (opsional)
ADMIN_PASSWORD	—	Password untuk akun admin awal (opsional)
SOURCE_PATH	data/	Path ke file JSON (hanya dengan build tag fs)

Catatan: Endpoint auth, komunitas (write), kontribusi, dan admin membutuhkan MySQL (MYSQL_DSN harus diset). Tanpa MySQL, hanya endpoint kamus publik (/alphabets, /entries) yang terdaftar.

Cara Menjalankan

# Dengan MySQL
MYSQL_DSN="user:pass@tcp(localhost:3306)/kamusbanjar" \
JWT_SECRET="your-secret-key-at-least-32-chars" \
go run .

# Hanya kamus (tanpa MySQL)
go run .

Cara Menjalankan Tes

Jalankan perintah berikut untuk melakukan test:

go test -v -cover ./...

Untuk integration test (membutuhkan database MySQL test):

TEST_MYSQL_DSN="user:pass@tcp(localhost:3306)/kamusbanjar_test" \
go test -tags=integration -v ./integration/...

Cara Membuat File Biner

Jalankan perintah berikut untuk membuat file biner:

go build -ldflags "-s -w" -o ./bin/app .

Kemudian jalankan menggunakan perintah ./bin/app.

Migrasi Database

Jalankan migrasi secara berurutan:

mysql -u user -p kamusbanjar < database/migrations/001_schema.sql
mysql -u user -p kamusbanjar < database/seeds/002_seed.sql
mysql -u user -p kamusbanjar < database/migrations/003_refresh_tokens.sql
mysql -u user -p kamusbanjar < database/migrations/004_word_source.sql
mysql -u user -p kamusbanjar < database/migrations/005_contributions.sql
mysql -u user -p kamusbanjar < database/migrations/006_community.sql

Atau gunakan Docker Compose yang otomatis menjalankan semua migrasi saat pertama kali dijalankan.

Docker

Development

cp .env.dev.example .env.dev
docker compose -f docker-compose.dev.yml --env-file .env.dev up -d

API tersedia di http://localhost:8001. MySQL tersedia di localhost:3306.
Untuk wipe dan re-seed: docker compose -f docker-compose.dev.yml down -v

Production (Traefik)

Jalankan Traefik terlebih dahulu:

cd traefik/ && docker compose up -d && cd ..

Kemudian:

cp .env.example .env
# Edit .env — wajib: DOMAIN, MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD, JWT_SECRET
docker compose up -d

API tersedia di https://<DOMAIN> dengan TLS otomatis dari Let's Encrypt.
Untuk wipe dan re-seed: docker compose down -v

Penggunaan

[GET] /api/v1/alphabets

Mengembalikan semua daftar alfabet.

Respon sukses

Respon akan dikembalikan dalam bentuk JSON. Contohnya:

{
  "code": 200,
  "data": [
    {
      "letter": "a",
      "total": 3
    }
  ],
  "message": "All alphabets successfully retrieved.",
  "status": "success"
}

Respon galat

Respon akan dikembalikan dalam bentuk JSON juga jika terdapat galat. Contohnya:

{
    "code": 500,
    "message": "Internal Server Error",
    "status": "error"
}

[GET] /api/v1/alphabets/{letter}

Mengembalikan daftar kosakata bahasa Banjar berdasarkan alfabet yang diberikan.

Parameters

Name	Keberadaan	Tipe	Deskripsi
letter	wajib	param	Huruf alfabet

Respon sukses

Respon akan dikembalikan dalam bentuk JSON. Contohnya:

{
  "code": 200,
  "data": {
    "letter": "a",
    "total": 3,
    "words": [
      "abadan",
      "abah",
      "abat"
    ]
  },
  "message": "All words with letter 'a' successfully retrieved.",
  "status": "success"
}

[GET] /api/v1/entries/{word}

Mengembalikan definisi dan arti dari kosakata bahasa Banjar yang diberikan.

Parameters

Name	Keberadaan	Tipe	Deskripsi
word	wajib	param	kosakata bahasa Banjar.

Respon sukses

Respon akan dikembalikan dalam bentuk JSON. Contohnya:

{
  "code": 200,
  "data": {
    "word": "abah",
    "alphabet": "a",
    "meanings": [
      {
        "definitions": [
          {
            "definition": "ayah",
            "partOfSpeech": "n"
          }
        ]
      }
    ]
  },
  "message": "Definition of word 'abah' successfully retrieved.",
  "status": "success"
}

Daftar Pustaka

• Departemen Pendidikan Nasional, Pusat Bahasa, Balai Bahasa Banjarmasin. 2008. Kamus Bahasa Banjar Dialek Hulu-Indonesia. Banjarbaru.
• Pusat Pembinaan dan Pengembangan Bahasa, Departemen Pendidikan dan Kebudayaan. 1977. Kamus Banjar-Indonesia. Jakarta.

Lisensi

Kamus Banjar API adalah perangkat lunak open-source yang dilisensikan di bawah lisensi MIT license.