Alur Kontribusi API Baru

Kontribusi ke repository ini selalu berbentuk penambahan satu entri ke berkas data kategori, bukan perubahan kode. CONTRIBUTING.md menetapkan empat langkah wajib: fork dan buat branch dari master, tambahkan RESTful API ke semua berkas bahasa yang tersedia, jalankan bun check lalu bun start, dan ajukan pull request ke branch master (CONTRIBUTING.md:15-32). Halaman ini memetakan langkah-langkah itu ke berkas nyata di repository, dari issue template sampai review pengelola.

Alur dari issue template sampai pull request

Diagram berikut menunjukkan perpindahan satu entri API: dimulai dari form issue, melewati penyuntingan berkas data, lalu diperiksa oleh src/check.ts ketika pull request dibuka.

graph TD
  issue["Issue: tambah_api.md\nlabels: api-baru"] --> edit["Sunting data/<kategori>/id.json\ndan en.json"]
  edit --> types["ItemType di src/types.ts"]
  types --> pr["Pull request ke branch master"]
  pr --> hook["Workflow NSFW Check\non: pull_request opened"]
  hook --> check["bun check\nsrc/check.ts"]
  check -->|lolos| review["Review pengelola"]
  check -->|gagal| reject["process.exit(1)"]
  review --> merge["merge ke master"]

  style edit fill:#2d7d46,color:#fff
  style check fill:#f59e0b,color:#000
  style pr fill:#336791,color:#fff
  style reject fill:#dc2626,color:#fff
  style merge fill:#8b5cf6,color:#fff
%% fig: Alur kontribusi satu entri API
%% desc: Entri bergerak dari issue template ke berkas data kedua bahasa, lalu diperiksa otomatis oleh bun check sebelum masuk review dan merge.

Fig. 1: Alur kontribusi satu entri APIEntri bergerak dari issue template ke berkas data kedua bahasa, lalu diperiksa otomatis oleh bun check sebelum masuk review dan merge.

Issue template sebagai checklist

.github/ISSUE_TEMPLATE/tambah_api.md sudah membawa labels: api-baru di frontmatter-nya, sehingga setiap issue baru otomatis masuk antrean yang sama dengan pull request (.github/ISSUE_TEMPLATE/tambah_api.md:1-6). Badan template meminta tujuh informasi dan satu penjelasan (.github/ISSUE_TEMPLATE/tambah_api.md:8-20).

Ketujuh informasi itu bukan prosa bebas: masing-masing berpasangan dengan kunci di ItemType (src/types.ts:1-8).

Isian issue template	Kunci di `data/<kategori>/<lang>.json`	Tipe di `src/types.ts`
Nama API	`apiName`	`string`
Tautan Dokumentasi	`documentationUrl`	`string`
Status	`status`	`boolean`
Pengembang	`developer.name`	`string`
Tautan Profil Pengembang	`developer.profileUrl`	`string \| null`
Deskripsi	`description`	`string`
Autentikasi	`authentication`	`string \| false`

Nilai authentication boleh false bila API tidak memerlukan kunci; contohnya entri Dayoff API memakai "authentication": false (data/general/id.json:4-14). Bila API memakai kunci, isi dengan true seperti entri ResitaApi (data/general/id.json:15-25).

Satu hal yang tidak ada di ItemType tetapi diminta template adalah pernyataan penutup bahwa tautan tidak mengandung konten NSFW (.github/ISSUE_TEMPLATE/tambah_api.md:24). Pernyataan itu bukan formalitas: src/check.ts benar-benar mengambil isi body setiap URL dan menghentikan proses bila menemukan kata blacklist (src/check.ts:52-55).

Menyunting berkas data kedua bahasa

CONTRIBUTING.md menegaskan bahwa satu entri harus ditambahkan ke semua berkas bahasa yang tersedia, misalnya id.json dan en.json (CONTRIBUTING.md:21-23). Setiap kategori adalah direktori di bawah data/, dan setiap direktori berisi satu berkas per bahasa — misalnya data/general/id.json dan data/general/en.json. Isi kategori diletakkan pada categoryName, sedangkan entri API berada di array apis; struktur itu tercermin di CategoryType (src/types.ts:10-13).

Yang berbeda antar bahasa hanyalah nilai categoryName dan description. Pada data/general/id.json kategori bernama Umum dengan deskripsi berbahasa Indonesia (data/general/id.json:1-13), sementara pasangannya memakai General dan deskripsi bahasa Inggris (data/general/en.json:1-13). Kunci apiName, documentationUrl, developer, dan authentication tetap identik di kedua berkas.

⚠️ Jangan menyalin entri ke bahasa lain dengan menerjemahkan apiName. Nama API adalah identifier yang dipakai untuk pengurutan otomatis: src/build.ts mengurutkan array apis dengan apiName.localeCompare, sehingga nama yang berbeda antar bahasa menghasilkan urutan tabel yang berbeda (src/build.ts:17-18).

Berkas yang dibaca bun check tidak didaftar manual. getFiles menelusuri direktori data/ secara rekursif dan mengumpulkan setiap berkas berekstensi .json (src/utils/index.ts:13-33). Artinya berkas baru di direktori kategori mana pun otomatis ikut diperiksa, dan berkas .json yang salah tempat juga ikut terbaca.

Gerbang otomatis sebelum review

Pemeriksaan berjalan tanpa perlu dipicu pengelola. Workflow NSFW Check bereaksi pada event pull_request bertipe opened dan reopened, memasang Bun versi 0.8.0, lalu menjalankan bun check (.github/workflows/nsfw-check.yml:1-27). Perintah itu sama dengan yang dijalankan kontributor secara lokal, karena package.json memetakan check ke bun run src/check.ts (package.json:36-42).

src/check.ts memeriksa empat hal berurutan, dan semuanya menghentikan proses lewat process.exit(1):

Pemeriksaan	Kondisi gagal	Pesan
Duplikat URL	`documentationUrl` yang sama muncul dua kali dalam satu berkas kategori	`Duplikat documentationUrl di ${file}: ${url}` (src/check.ts:12-25)
Kunci wajib	`documentationUrl` tidak ada atau kosong	`documentationUrl is required.` (src/check.ts:27-31)
Konten NSFW	body response memuat kata dari blacklist	`Sorry, the NSFW API is not allowed here :)` (src/check.ts:52-55)
Timeout	request tidak selesai dalam `10_000` ms	`signal: AbortSignal.timeout(10_000)` (src/check.ts:43-49)

Dua perilaku lain perlu diketahui sebelum menekan tombol pull request. Pertama, fragmen anchor dibuang dari URL sebelum dibandingkan, sehingga https://contoh.id#dokumentasi dan https://contoh.id dihitung sebagai duplikat dalam berkas yang sama (src/check.ts:16-24). Kedua, isBlacklisted hanya melakukan pencocokan substring pada body response, dan daftar katanya diimpor dari ../data/blacklist.json (src/utils/index.ts:35-37). Karena itu URL yang sedang down pun bisa lolos tanpa status sukses: blok catch dibiarkan kosong dan hanya mencatat log [ ... ] (src/check.ts:40-59).

Kontributor juga dapat menjalankan bun start sesuai CONTRIBUTING.md (CONTRIBUTING.md:25-27). Perintah itu memetakan ke bun run src/build.ts (package.json:39) dan menulis ulang seluruh isi blok  sampai  di README (src/build.ts:95-98). Untuk memahami efeknya, lihat Pipeline Build Markdown dan Mode Rewrite dan Status API.

⚠️ Jangan mengandalkan bun start sebagai pengganti bun check. Build tidak menolak duplikat, sedangkan bun check menolaknya. Jalankan bun check lebih dulu agar pull request tidak langsung merah di workflow NSFW Check.

Commit, review, dan setelah merge

CONTRIBUTING.md meminta commit dengan deskripsi jelas, push ke branch di repository hasil fork, lalu pull request ke branch master (CONTRIBUTING.md:29-32). Hook pre-commit di package.json menjalankan bun format dan git add --all, sehingga setiap commit otomatis tertata mengikuti konfigurasi Prettier di berkas yang sama (package.json:20-25).

Setelah pull request di-merge, pengelola menanggung sisa pekerjaan lewat Otomasi GitHub Actions: workflow Build Merge menjalankan bun start lalu membuat commit chore(readme): update (.github/workflows/build-merge.yml:25-34). Kontributor tidak perlu menyunting berkas README secara manual, karena bagian itu ditulis ulang oleh build. README sendiri hanya menautkan panduan lengkap ke CONTRIBUTING.md (README.md:304-306).

Dengan mengajukan pull request, kontribusi dianggap dilisensikan di bawah Attribution 4.0 International (CONTRIBUTING.md:73-75). Semua peserta juga terikat pada kode etik, termasuk larangan menyebarkan konten pornografi (CONTRIBUTING.md:5-7). Pelanggaran kode etik tidak ditangani oleh src/check.ts, melainkan oleh proses review manusia. Bila API yang sudah terdaftar kemudian mati, siklus penonaktifan dan penghapusan diatur aturan stabilitas, bukan oleh alur penambahan ini (CONTRIBUTING.md:54-65).

Untuk menyiapkan lingkungan kerja sebelum menjalankan bun check, lihat Menjalankan Proyek di Lokal.