API HolyArrs

Panggil API JSON yang sama dengan yang dipakai aplikasi web, di bawah /api/v1, dari skrip kamu sendiri.

Panggilan pertama

1. Buka Settings > API > API keys (pengaturan > API > kunci API) lalu buat kunci dengan scope yang dibutuhkan saja. Salin sekarang, karena kunci hanya ditampilkan sekali.
2. Kirim kunci di header X-Api-Key pada setiap panggilan. Jangan pernah menaruhnya di alamat.
3. Panggil alamat dasar http://your-server:6262/api/v1. Kalau URL base-nya /holyarrs, panggil http://your-server:6262/holyarrs/api/v1.

export HOLYARRS_KEY=...your key...
curl -H "X-Api-Key: $HOLYARRS_KEY" "http://your-server:6262/api/v1/health"

Kamu akan mendapat JSON. Kesalahan berbentuk {"error": "plain words"} dengan status HTTP. Rahasia dikembalikan dalam bentuk tersamar.

Pilihan

Pilih scope

Scope	Mengizinkan
health_read	Hanya feed kondisi, untuk alat pemantau
read	Route baca, termasuk feed kondisi
write	Perubahan, kecuali route admin dan kontrol
admin	Pengguna, undangan, batas permintaan, kunci API, kata sandi dan dua faktor, pengaturan login, pemulihan
control	Sakelar bagian, tahap, aplikasi tertaut, memulai ulang dan mematikan
all	read, write dan admin. Bukan control

Beri alat pemantau health_read saja.

Cari sebuah route

Settings > API menampilkan alamat dasar, scope, contoh panggilan, dan setiap route beserta scope dan izinnya. File OpenAPI ada di /api/v1/openapi.json kalau kamu sudah login. Route API mencantumkan semua route.

Bicara dengan HolyArrs sebagai aplikasi lama

Seerr, Overseerr, Bazarr dan aplikasi sejenis tidak memakai API ini. Mereka bicara dengan HolyArrs seolah-olah itu Sonarr dan Radarr, dengan kunci mereka sendiri. Lihat API aplikasi lama.

Kalau tidak berhasil

Gejala. 401 di setiap panggilan. Penyebab. Kuncinya salah atau sudah dihapus. Solusi. Buat kunci baru.

Gejala. 403 di satu route. Penyebab. Scope kunci tidak mencakup route itu. Solusi. Periksa scope route itu di Settings > API.

Gejala. 404 di setiap panggilan. Penyebab. URL base belum disertakan. Solusi. Taruh sebelum /api/v1. Lihat URL base.

Untuk yang mahir

Menambahkan route

Route ada di routes.go milik tiap modul. Setiap route didaftarkan dengan metode, path dan izinnya, jadi setiap route punya pemeriksaan izin.

openapi.json dibuat dari route. TestOpenAPIGenerated gagal kalau keduanya tidak sama, jadi perbarui di perubahan yang sama. Snapshot tabel route juga gagal kalau sebuah route ditambah, dihapus atau dipindah tanpa memperbarui snapshot.

Setelah dirilis, path dan nama field tetap. Tambahkan field, jangan ganti namanya. Setelah ada perubahan, jalankan go run ./app/backend/tools/apidoc untuk menulis ulang Route API.

Panggilan ke server metadata

HolyArrs mengambil nama, gambar dan id dari server metadata HolyArrs. Arahkan sebuah instalasi ke server lain dengan HOLYARRS_METADATA_URL. Kode servernya tidak ada di repo ini.

Pendaftaran. Pada pencarian pertamanya, sebuah instalasi memanggil POST /v1/installations tanpa isi. Jawabannya 201 dengan {"schema_version":1,"token":"hai_..."}. Aplikasi menyimpan token itu terenkripsi dan mengirim Authorization: Bearer <token> di setiap pencarian. Pendaftaran hanya dilakukan sekali. Setelah 401 aplikasi tidak mendaftar lagi, jadi instalasi yang dicabut tetap tercabut. Kalau melewati batas per jam untuk satu grup alamat, jawabannya 429 registration_limit dengan Retry-After.

Pencarian (semua GET)	Route
Pencarian	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Serial	/v1/shows/{tmdb or tvmaze}/{id}
Musim	/v1/shows/tmdb/{id}/seasons/{n} (musim 0 adalah spesial)
Musik	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Parameter yang tidak dikenal atau berulang ditolak. Id dari satu penyedia tidak pernah dipakai untuk penyedia lain.

Jawaban yang baik berisi schema_version, source, source_id, fetched_at, expires_at, completeness, stale dan data. Perlakukan HTML di ringkasan sebagai teks biasa.

Status	Artinya
400	Query salah, jangan coba lagi
401	Token salah atau dicabut, jangan coba lagi
404	Tidak ada data seperti itu
429	Terlalu banyak panggilan, tunggu Retry-After
503	Sibuk, tunggu lalu coba sekali lagi

Terkait

• Route API
• API aplikasi lama
• Variabel lingkungan