API-ul HolyArrs

Apelează din propriile scripturi același API JSON pe care îl folosește aplicația web, sub /api/v1.

Fă primul apel

1. Deschide Settings > API > API keys (Setări > API > chei API) și fă o cheie doar cu scopurile de care are nevoie. Copiază-o acum, pentru că apare o singură dată.
2. Trimite-o în antetul X-Api-Key la fiecare apel. Nu o pune niciodată în adresă.
3. Apelează adresa de bază http://your-server:6262/api/v1. Dacă ai URL base /holyarrs, apelează 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"

Ar trebui să primești JSON înapoi. Erorile arată așa: {"error": "plain words"}, împreună cu un cod de stare HTTP. Secretele vin mascate.

Alegeri

Alege un scop

Scop	Permite
health_read	Doar fluxul de sănătate, pentru unelte de monitorizare
read	Rutele de citire, inclusiv fluxul de sănătate
write	Modificări, în afară de rutele de administrare și de comenzi
admin	Persoane, invitații, limite de cereri, chei API, parole și autentificare în doi pași, setări de conectare, restaurare
control	Comutatoarele pentru părți, etape, aplicații conectate, repornire și oprire
all	read, write și admin. Nu și control

Dă unei unelte de monitorizare health_read și nimic altceva.

Găsește o rută

Settings > API arată adresa de bază, scopurile, exemple de apeluri și fiecare rută cu scopul și permisiunea ei. Fișierul OpenAPI este la /api/v1/openapi.json când ești conectat. Rute API le listează pe toate.

Vorbește cu HolyArrs ca o aplicație mai veche

Seerr, Overseerr, Bazarr și alte aplicații asemănătoare nu folosesc acest API. Ele vorbesc cu HolyArrs ca și cum ar fi Sonarr și Radarr, cu chei proprii. Vezi API pentru aplicații mai vechi.

Dacă nu merge

Simptom. Eroare 401 la fiecare apel. Cauză. Cheia este greșită sau ștearsă. Soluție. Fă o cheie nouă.

Simptom. Eroare 403 la o singură rută. Cauză. Scopul cheii nu acoperă ruta respectivă. Soluție. Verifică scopul rutei în Settings > API.

Simptom. Eroare 404 la fiecare apel. Cauză. Lipsește URL base. Soluție. Pune-l înainte de /api/v1. Vezi URL base.

Pentru experți

Adaugă o rută

Rutele stau în routes.go din fiecare modul. Fiecare este înregistrată cu metoda, calea și permisiunea ei, deci orice rută are o verificare de permisiune.

openapi.json este generat din rute. TestOpenAPIGenerated pică dacă nu mai se potrivesc, așa că actualizează-l în aceeași modificare. Și un instantaneu al tabelului de rute pică dacă o rută este adăugată, scoasă sau mutată fără să actualizezi instantaneul.

După ce o rută a apărut într-o versiune, căile și numele câmpurilor rămân. Adaugă câmpuri, nu le redenumi niciodată. După o schimbare, rulează go run ./app/backend/tools/apidoc ca să rescrii Rute API.

Apeluri către serverul de metadate

HolyArrs ia nume, imagini și id-uri de la serverul de metadate HolyArrs. Poți îndrepta o instalare spre alt server cu HOLYARRS_METADATA_URL. Codul serverului nu este în acest depozit.

Înregistrare. La prima căutare, o instalare apelează POST /v1/installations fără corp. Răspunsul este 201 cu {"schema_version":1,"token":"hai_..."}. Aplicația păstrează token-ul criptat și trimite Authorization: Bearer <token> la fiecare căutare. Se înregistrează o singură dată. După un 401 nu se mai înregistrează, deci o instalare revocată rămâne revocată. Peste limita pe oră pentru un grup de adrese, răspunsul este 429 registration_limit cu Retry-After.

Căutare (toate GET)	Rută
Căutare	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Serial	/v1/shows/{tmdb or tvmaze}/{id}
Sezon	/v1/shows/tmdb/{id}/seasons/{n} (sezonul 0 înseamnă episoadele speciale)
Muzică	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Parametrii necunoscuți sau repetați sunt refuzați. Id-urile de la un furnizor nu se folosesc niciodată pentru altul.

Un răspuns bun are schema_version, source, source_id, fetched_at, expires_at, completeness, stale și data. Tratează HTML-ul din rezumate ca text simplu.

Stare	Înseamnă
400	Cerere greșită, nu încerca din nou
401	Token greșit sau revocat, nu încerca din nou
404	Nu există o astfel de înregistrare
429	Prea multe apeluri, așteaptă după Retry-After
503	Ocupat, așteaptă și încearcă încă o dată

Vezi și

• Rute API
• API pentru aplicații mai vechi
• Variabile de mediu