Το API του HolyArrs

Κάλεσε από τα δικά σου scripts το ίδιο JSON API που χρησιμοποιεί η διαδικτυακή εφαρμογή, κάτω από το /api/v1.

Κάνε την πρώτη σου κλήση

1. Άνοιξε Settings > API > API keys (Ρυθμίσεις > API > κλειδιά API) και φτιάξε ένα κλειδί μόνο με τα scopes που χρειάζεται. Αντίγραψέ το αμέσως, γιατί εμφανίζεται μία φορά.
2. Στείλε το στην κεφαλίδα X-Api-Key σε κάθε κλήση. Μην το βάζεις ποτέ στη διεύθυνση.
3. Κάλεσε τη βασική διεύθυνση http://your-server:6262/api/v1. Αν το URL base είναι /holyarrs, κάλεσε το 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"

Θα πρέπει να πάρεις JSON πίσω. Τα σφάλματα έρχονται ως {"error": "plain words"} μαζί με ένα HTTP status. Τα μυστικά επιστρέφονται καλυμμένα.

Επιλογές

Διάλεξε scope

Scope	Επιτρέπει
health_read	Μόνο το feed υγείας, για εργαλεία παρακολούθησης
read	Τα routes ανάγνωσης, μαζί με το feed υγείας
write	Αλλαγές, εκτός από τα routes διαχείρισης και τους ελέγχους
admin	Άτομα, προσκλήσεις, όρια αιτημάτων, κλειδιά API, κωδικούς πρόσβασης και έλεγχο ταυτότητας δύο παραγόντων, ρυθμίσεις σύνδεσης, επαναφορά
control	Διακόπτες ενοτήτων, στάδια, συνδεδεμένες εφαρμογές, επανεκκίνηση και τερματισμός
all	read, write και admin. Όχι control

Σε ένα εργαλείο παρακολούθησης δώσε health_read και τίποτα άλλο.

Βρες ένα route

Το Settings > API δείχνει τη βασική διεύθυνση, τα scopes, παραδείγματα κλήσεων και κάθε route με το scope και το δικαίωμά του. Το αρχείο OpenAPI βρίσκεται στο /api/v1/openapi.json όταν έχεις κάνει σύνδεση. Η σελίδα Διαδρομές API τα έχει όλα.

Μίλα στο HolyArrs σαν να είναι παλαιότερη εφαρμογή

Το Seerr, το Overseerr, το Bazarr και παρόμοιες εφαρμογές δεν χρησιμοποιούν αυτό το API. Μιλούν στο HolyArrs σαν να είναι Sonarr και Radarr, με δικά τους κλειδιά. Δες το API παλαιότερων εφαρμογών.

Αν δεν δουλεύει

Σύμπτωμα. 401 σε κάθε κλήση. Αιτία. Το κλειδί είναι λάθος ή έχει διαγραφεί. Λύση. Φτιάξε νέο κλειδί.

Σύμπτωμα. 403 σε ένα route. Αιτία. Το scope του κλειδιού δεν καλύπτει αυτό το route. Λύση. Έλεγξε το scope του route στο Settings > API.

Σύμπτωμα. 404 σε κάθε κλήση. Αιτία. Λείπει το URL base. Λύση. Βάλε το πριν από το /api/v1. Δες το URL base.

Για έμπειρους

Πρόσθεσε ένα route

Τα routes ζουν στο routes.go κάθε ενότητας. Κάθε route καταχωρίζεται με τη μέθοδο, τη διαδρομή και το δικαίωμά του, οπότε κάθε route έχει έλεγχο δικαιώματος.

Το openapi.json προκύπτει από τα routes. Το TestOpenAPIGenerated αποτυγχάνει όταν δεν συμφωνούν, γι’ αυτό ενημέρωσέ το στην ίδια αλλαγή. Ένα snapshot του πίνακα routes αποτυγχάνει επίσης όταν ένα route προστίθεται, αφαιρείται ή μετακινείται χωρίς ενημέρωση του snapshot.

Μόλις βγει σε έκδοση, οι διαδρομές και τα ονόματα των πεδίων μένουν ίδια. Πρόσθεσε πεδία, μην τα μετονομάζεις ποτέ. Μετά από μια αλλαγή, τρέξε go run ./app/backend/tools/apidoc για να ξαναγραφτεί η σελίδα Διαδρομές API.

Κλήσεις προς τον διακομιστή μεταδεδομένων

Το HolyArrs παίρνει ονόματα, εικόνες και ids από τον διακομιστή μεταδεδομένων του HolyArrs. Για να δείξεις μια εγκατάσταση σε άλλον διακομιστή, χρησιμοποίησε το HOLYARRS_METADATA_URL. Ο κώδικας του διακομιστή δεν είναι σε αυτό το repo.

Εγγραφή. Στην πρώτη αναζήτηση, μια εγκατάσταση καλεί το POST /v1/installations χωρίς σώμα. Η απάντηση είναι 201 με {"schema_version":1,"token":"hai_..."}. Η εφαρμογή αποθηκεύει το token κρυπτογραφημένο και στέλνει Authorization: Bearer <token> σε κάθε αναζήτηση. Εγγράφεται μία φορά. Μετά από ένα 401 δεν εγγράφεται ξανά, οπότε μια εγκατάσταση που ανακλήθηκε μένει ανακληθείσα. Αν περάσει το ωριαίο όριο ανά ομάδα διευθύνσεων, η απάντηση είναι 429 registration_limit με Retry-After.

Αναζήτηση (όλα GET)	Route
Αναζήτηση	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Ταινία	/v1/movies/tmdb/{id}
Σειρά	/v1/shows/{tmdb or tvmaze}/{id}
Σεζόν	/v1/shows/tmdb/{id}/seasons/{n} (η σεζόν 0 είναι τα ειδικά επεισόδια)
Μουσική	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Άγνωστες ή επαναλαμβανόμενες παράμετροι απορρίπτονται. Τα ids ενός provider δεν χρησιμοποιούνται ποτέ για άλλον.

Μια σωστή απάντηση έχει τα schema_version, source, source_id, fetched_at, expires_at, completeness, stale και data. Αντιμετώπισε το HTML στις περιλήψεις ως απλό κείμενο.

Status	Σημαίνει
400	Λάθος ερώτημα, μην ξαναδοκιμάσεις
401	Λάθος ή ανακληθέν token, μην ξαναδοκιμάσεις
404	Δεν υπάρχει τέτοια εγγραφή
429	Πολλές κλήσεις, περίμενε το Retry-After
503	Απασχολημένος, περίμενε και δοκίμασε μία φορά ξανά

Σχετικά

• Διαδρομές API
• API παλαιότερων εφαρμογών
• Μεταβλητές περιβάλλοντος