API HolyArrs

Panggil API JSON yang sama seperti yang digunakan app web, di bawah /api/v1, daripada skrip anda sendiri.

Buat panggilan pertama

1. Buka Settings > API > API keys (Tetapan > API > kunci API) dan buat kunci dengan skop yang diperlukan sahaja. Salin sekarang, kerana kunci hanya dipaparkan sekali.
2. Hantar kunci dalam header X-Api-Key pada setiap panggilan. Jangan letakkan dalam alamat.
3. Panggil alamat asas http://your-server:6262/api/v1. Jika URL base ialah /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"

Anda akan mendapat JSON. Ralat dipaparkan sebagai {"error": "plain words"} bersama status HTTP. Rahsia dikembalikan dalam bentuk tersembunyi.

Pilihan

Pilih skop

Skop	Membenarkan
health_read	Feed kesihatan sahaja, untuk alat pemantauan
read	Route baca, termasuk feed kesihatan
write	Perubahan, kecuali route pentadbir dan kawalan
admin	Orang, jemputan, had permintaan, kunci API, kata laluan dan dua faktor, tetapan log masuk, pemulihan
control	Suis bahagian, peringkat, app terpaut, mula semula dan matikan
all	read, write dan admin. Bukan control

Beri alat pemantauan health_read dan tiada yang lain.

Cari route

Settings > API memaparkan alamat asas, skop, contoh panggilan, dan setiap route beserta skop dan kebenarannya. Fail OpenAPI ada di /api/v1/openapi.json apabila anda sudah log masuk. Laluan API menyenaraikan setiap route.

Bercakap dengan HolyArrs sebagai app lama

Seerr, Overseerr, Bazarr dan app seumpamanya tidak menggunakan API ini. App itu bercakap dengan HolyArrs seolah-olah ia Sonarr dan Radarr, dengan kunci tersendiri. Lihat API app lama.

Jika tidak berfungsi

Gejala. 401 pada setiap panggilan. Punca. Kunci salah atau sudah dipadam. Penyelesaian. Buat kunci baharu.

Gejala. 403 pada satu route. Punca. Skop kunci tidak meliputi route itu. Penyelesaian. Semak skop route itu di Settings > API.

Gejala. 404 pada setiap panggilan. Punca. URL base tiada. Penyelesaian. Letakkannya sebelum /api/v1. Lihat URL base.

Untuk pakar

Tambah route

Route berada dalam routes.go setiap modul. Setiap satu didaftarkan dengan kaedah, laluan dan kebenarannya, jadi setiap route ada semakan kebenaran.

openapi.json dihasilkan daripada route. TestOpenAPIGenerated gagal apabila keduanya tidak sepadan, jadi kemas kininya dalam perubahan yang sama. Snapshot jadual route juga gagal apabila sebuah route ditambah, dibuang atau dialihkan tanpa kemas kini snapshot.

Selepas dikeluarkan, laluan dan nama medan kekal. Tambah medan, jangan namakan semula. Selepas perubahan, jalankan go run ./app/backend/tools/apidoc untuk menulis semula Laluan API.

Panggilan pelayan metadata

HolyArrs mendapat nama, gambar dan id daripada pelayan metadata HolyArrs. Halakan pemasangan ke pelayan lain dengan HOLYARRS_METADATA_URL. Kod pelayan tiada dalam repo ini.

Pendaftaran. Pada carian pertamanya, pemasangan memanggil POST /v1/installations tanpa body. Jawapannya 201 dengan {"schema_version":1,"token":"hai_..."}. App menyimpan token dalam bentuk disulitkan dan menghantar Authorization: Bearer <token> pada setiap carian. Ia mendaftar sekali sahaja. Selepas 401, ia tidak mendaftar lagi, jadi pemasangan yang dibatalkan kekal dibatalkan. Jika melebihi had sejam bagi setiap kumpulan alamat, jawapannya 429 registration_limit dengan Retry-After.

Carian (semua GET)	Route
Carian	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Filem	/v1/movies/tmdb/{id}
Siri	/v1/shows/{tmdb or tvmaze}/{id}
Musim	/v1/shows/tmdb/{id}/seasons/{n} (musim 0 ialah episod khas)
Muzik	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Parameter yang tidak dikenali atau berulang akan ditolak. Id daripada satu penyedia tidak pernah digunakan untuk penyedia lain.

Jawapan yang baik mengandungi schema_version, source, source_id, fetched_at, expires_at, completeness, stale dan data. Anggap HTML dalam ringkasan sebagai teks biasa.

Status	Maksud
400	Pertanyaan tidak sah, jangan cuba lagi
401	Token tidak sah atau dibatalkan, jangan cuba lagi
404	Tiada rekod sedemikian
429	Terlalu banyak panggilan, tunggu Retry-After
503	Sibuk, tunggu dan cuba sekali lagi

Berkaitan

• Laluan API
• API app lama
• Pemboleh ubah persekitaran