HolyArrsi API

Kutsu oma skriptidest sama JSON API-t, mida kasutab veebirakendus, aadressil /api/v1.

Tee esimene päring

1. Ava Settings > API > API keys (seaded > API > API-võtmed) ja tee võti, millel on ainult vajalikud skoobid. Kopeeri see kohe ära, sest see näidatakse ainult üks kord.
2. Saada see igas päringus päises X-Api-Key. Ära pane seda kunagi aadressi.
3. Kasuta baasaadressi http://your-server:6262/api/v1. Kui URL base on /holyarrs, kasuta 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"

Sa peaksid saama vastuseks JSON-i. Vead on kujul {"error": "plain words"} koos HTTP olekukoodiga. Saladused tulevad tagasi maskeerituna.

Valikud

Vali skoop

Skoop	Lubab
health_read	Ainult tervisevoogu, seirevahenditele
read	Lugemismarsruute, tervisevoog kaasa arvatud
write	Muutmisi, välja arvatud admini marsruudid ja juhtimine
admin	Inimesi, kutseid, soovide limiite, API-võtmeid, paroole ja kaheastmelist kinnitamist, sisselogimise sätteid, taastamist
control	Osade lülitid, etapid, ühendatud rakendused, taaskäivitamine ja väljalülitamine
all	read, write ja admin. Mitte control

Anna seirevahendile health_read ja mitte midagi muud.

Leia marsruut

Leht Settings > API näitab baasaadressi, skoope, näidispäringuid ja iga marsruuti koos selle skoobi ja õigusega. OpenAPI fail asub aadressil /api/v1/openapi.json, kui oled sisse logitud. Kõik marsruudid on loetletud lehel API marsruudid.

Räägi HolyArrsiga nagu vanem rakendus

Seerr, Overseerr, Bazarr ja sarnased rakendused ei kasuta seda API-t. Nad räägivad HolyArrsiga nii, nagu oleks see Sonarr ja Radarr, ning kasutavad oma võtmeid. Vaata lehte Vanade rakenduste API.

Kui see ei tööta

Sümptom. Iga päring annab vea 401. Põhjus. Võti on vale või kustutatud. Lahendus. Tee uus võti.

Sümptom. Üks marsruut annab vea 403. Põhjus. Võtme skoop ei kata seda marsruuti. Lahendus. Vaata marsruudi skoopi lehelt Settings > API.

Sümptom. Iga päring annab vea 404. Põhjus. URL base puudub. Lahendus. Pane see enne /api/v1. Vaata lehte URL base.

Asjatundjale

Lisa marsruut

Marsruudid asuvad iga mooduli failis routes.go. Igaüks registreeritakse oma meetodi, tee ja õigusega, nii et igal marsruudil on õiguse kontroll.

openapi.json tehakse marsruutidest. TestOpenAPIGenerated kukub läbi, kui need lähevad lahku, seega uuenda seda samas muudatuses. Marsruuditabeli hetktõmmis kukub samuti läbi, kui marsruut lisatakse, eemaldatakse või teisaldatakse ilma hetktõmmist uuendamata.

Kui versioon on välja antud, jäävad teed ja väljade nimed samaks. Lisa välju, aga ära neid kunagi ümber nimeta. Pärast muudatust käivita go run ./app/backend/tools/apidoc, et lehte API marsruudid uuesti kirjutada.

Metaandmete serveri päringud

HolyArrs saab nimed, pildid ja id-d HolyArrsi metaandmete serverist. Suuna paigaldus teise serveri peale muutujaga HOLYARRS_METADATA_URL. Serveri kood ei ole selles repos.

Registreerimine. Esimesel otsingul kutsub paigaldus välja POST /v1/installations ilma sisuta. Vastus on 201 koos {"schema_version":1,"token":"hai_..."}. Rakendus salvestab tokeni krüpteeritult ja saadab igas otsingus Authorization: Bearer <token>. See registreerub ainult üks kord. Pärast 401 ei registreeru see uuesti, nii et tühistatud paigaldus jääb tühistatuks. Kui tunnipiir aadressigrupi kohta ületatakse, on vastus 429 registration_limit koos Retry-After.

Otsing (kõik GET)	Marsruut
Otsing	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Sari	/v1/shows/{tmdb or tvmaze}/{id}
Hooaeg	/v1/shows/tmdb/{id}/seasons/{n} (hooaeg 0 on eriepisoodid)
Muusika	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Tundmatud või korduvad parameetrid lükatakse tagasi. Ühe pakkuja id-sid ei kasutata kunagi teise jaoks.

Hea vastus sisaldab väljasid schema_version, source, source_id, fetched_at, expires_at, completeness, stale ja data. Kohtle kokkuvõtetes olevat HTML-i lihttekstina.

Olek	Tähendab
400	Halb päring, ära proovi uuesti
401	Halb või tühistatud token, ära proovi uuesti
404	Sellist kirjet pole
429	Liiga palju päringuid, oota Retry-After aega
503	Hõivatud, oota ja proovi üks kord uuesti

Seotud lehed

• API marsruudid
• Vanade rakenduste API
• Keskkonnamuutujad