Skema Data Kategori

Semua data API yang ditampilkan di README berasal dari berkas JSON di bawah data/. Satu berkas mewakili satu kategori pada satu bahasa, dan bentuk isinya dikunci oleh tiga tipe di src/types.ts (src/types.ts:1-17¹). Halaman ini menjelaskan bentuk tipe itu, susunan path berkasnya, dan aturan konsistensi antar bahasa. Cara berkas-berkas ini dibaca menjadi tabel dijelaskan di Pipeline Build Markdown.

Relasi kategori, API, pengembang, dan status

erDiagram
  LANGUAGE ||--o{ CATEGORY : "kunci bahasa"
  CATEGORY ||--o{ API : "apis"
  API }o--|| DEVELOPER : "developer"
  LANGUAGE {
    string code
  }
  CATEGORY {
    string categoryName
  }
  API {
    string apiName
    boolean status
    string documentationUrl
    string description
    string_or_false authentication
  }
  DEVELOPER {
    string name
    string profileUrl
  }
  style LANGUAGE fill:#f59e0b,color:#000
  style CATEGORY fill:#336791,color:#fff
  style API fill:#336791,color:#fff
  style DEVELOPER fill:#8b5cf6,color:#fff
  %% fig: Relasi kategori, API, pengembang, dan status
  %% desc: Satu kunci bahasa memuat banyak kategori, setiap kategori memuat banyak API, dan setiap API merujuk tepat satu pengembang disertai status boolean.

CategoryType hanya punya dua field, yaitu categoryName dan apis, dan apis bertipe array ItemType (src/types.ts:10-13²). Setiap ItemType selalu membawa tepat satu developer, satu status boolean, dan satu authentication yang boleh bernilai false (src/types.ts:1-8³). Warna diagram mengikuti peran data: biru untuk entitas yang disimpan di JSON, kuning untuk kunci bahasa, ungu untuk data pendukung pengembang.

ListType menambah satu lapis di atas CategoryType: sebuah peta dari kunci bahasa ke array CategoryType (src/types.ts:15-17⁴). Entitas LANGUAGE pada diagram bukan tipe di repository, melainkan kunci ListType yang diambil dari nama berkas tanpa ekstensi lewat getLanguage (src/utils/index.ts:5-11⁵).

Field ItemType dan kolom markdown

Tabel berikut memetakan setiap field ke satu kolom tabel markdown. Nilai contoh diambil dari entri pertama data/islamic/id.json (data/islamic/id.json:1-14⁶).

Nilai "API KEY" pada baris terakhir berasal dari entri Qalbun API (data/islamic/id.json:92-102⁷). markdownBuilder yang merangkai sel-sel itu: developer menjadi tautan hanya bila profileUrl tidak null, status menjadi ✅ atau ❎, dan authentication yang false dicetak sebagai literal false (src/utils/markdown.ts:19-27⁸).

Karena nilai authentication ditempel apa adanya ke dalam sel, string itu boleh memuat penanda markdown. Entri PLN (Unofficial) menyimpan nilai "`x-api-key`", dan entri yang sama menaruh authentication sebelum documentationUrl sehingga urutan field di dalam berkas tidak dijaga (data/government/id.json:70-79⁹).

Susunan berkas data/<kategori>/<bahasa>.json

graph LR
  subgraph dataDir["data/"]
    idFile["islamic/id.json"]
    enFile["islamic/en.json"]
    musicFile["music/id.json"]
  end
  idFile -->|"CategoryType"| idList["data['id'] : CategoryType[]"]
  enFile -->|"CategoryType"| enList["data['en'] : CategoryType[]"]
  musicFile -->|"CategoryType"| idList
  idList --> idReadme["README.md"]
  enList --> enReadme["README.en.md"]
  style idFile fill:#336791,color:#fff
  style enFile fill:#336791,color:#fff
  style musicFile fill:#336791,color:#fff
  style idList fill:#8b5cf6,color:#fff
  style enList fill:#8b5cf6,color:#fff
  style idReadme fill:#2d7d46,color:#fff
  style enReadme fill:#2d7d46,color:#fff
  %% fig: Satu berkas per kategori per bahasa
  %% desc: Setiap berkas JSON adalah satu CategoryType yang dikumpulkan ke array per bahasa pada ListType, lalu menghasilkan satu README per bahasa.

Setiap berkas berisi satu objek CategoryType, bukan array, dengan categoryName diikuti apis (data/islamic/id.json:1-14⁶). getFiles menelusuri data/ secara rekursif dan mengambil setiap berkas berakhiran .json, sehingga kedalaman direktori tidak dibatasi (src/utils/index.ts:13-33¹⁰). Build kemudian memasukkan setiap hasil baca ke data[language] sebagai elemen array, lalu menulis satu README per bahasa — README.md untuk id dan README.en.md untuk en (src/build.ts:79-90¹¹).

Urutan entri di dalam berkas tidak menentukan urutan tabel. build.ts mengurutkan apis dengan localeCompare sebelum berkas diproses lebih lanjut (src/build.ts:18¹²).

Konsistensi antar bahasa

Kedua berkas islamic memakai apiName dan documentationUrl yang sama, tetapi menerjemahkan categoryName dan description (data/islamic/en.json:1-14¹³).

Hitungan entri di atas berasal dari seluruh isi kedua berkas (data/islamic/id.json:1-148¹⁴, data/islamic/en.json:1-148¹⁵). Jumlahnya sama, tetapi himpunan entrinya tidak identik: id.json memuat Waktu Sholat API (data/islamic/id.json:136-146¹⁶), sedangkan en.json memuat Prayer Times API (data/islamic/en.json:81-91¹⁷).

⚠️ Tidak ada pemeriksaan yang membandingkan berkas antar bahasa. check.ts berjalan per berkas dan hanya menolak documentationUrl duplikat di dalam satu berkas atau documentationUrl yang kosong (src/check.ts:9-31¹⁸). Entri yang lupa diterjemahkan tetap lolos dan hanya muncul di satu README. Rincian validator ada di Validator Data lewat check.ts.

Saat menambah API, tambahkan entri yang sama ke setiap berkas bahasa pada direktori kategori tersebut, dengan apiName dan documentationUrl identik serta description yang diterjemahkan. Langkah lengkapnya ada di Dukungan Multi-Bahasa dan Alur Kontribusi API Baru.