Baue mit der Hoshika-API

1. Registriere deine App

Jedes Hoshika-Konto kann OAuth-Zugangsdaten erstellen unter Einstellungen → Anwendungen.

• Redirect-URIs müssen https sein (http://localhost ist für Entwicklung erlaubt).
• Das Client-Secret wird nur einmal angezeigt — sicher aufbewahren.
• Bis zu 5 Apps pro Konto.

2. OAuth 2.0 (Authorization Code + PKCE)

Standard-Flow: Nutzer zur Autorisierung schicken, Zustimmung auf dem Consent-Screen, dann Code gegen Tokens tauschen. PKCE ist Pflicht.

# Discovery (OpenID Connect)
https://hoshika.app/api/auth/.well-known/openid-configuration

# 1) Authorization (PKCE required)
GET https://hoshika.app/api/auth/oauth2/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.example/callback
  &response_type=code
  &scope=openid profile offline_access
  &code_challenge=BASE64URL(SHA256(verifier))
  &code_challenge_method=S256

# 2) Token exchange
POST https://hoshika.app/api/auth/oauth2/token
  grant_type=authorization_code
  code=...&code_verifier=...&client_id=...&client_secret=...
  redirect_uri=https://yourapp.example/callback

# → { access_token, refresh_token, expires_in: 86400 }

Access Tokens gelten 24 Stunden; Refresh Tokens 90 Tage. Sende das Token als Authorization: Bearer bei jedem Aufruf.

3. Die API

Basis-URL https://hoshika.app/api/v1 — JSON rein und raus. Jede Antwort enthält ok, Fehler tragen einen stabilen maschinenlesbaren code.

curl https://hoshika.app/api/v1/library?type=anime \
  -H "Authorization: Bearer ACCESS_TOKEN"

# Upsert de progreso (campos parciales)
POST /api/v1/library/entry
{ "type": "anime", "mediaId": "<uuid>", "status": "watching",
  "progress": 7, "userScore": 8 }

# Contrato de error (siempre):
{ "ok": false, "code": "unauthorized" | "invalid" | "rate_limited" | ... }

4. Spielregeln

• Rate Limits gelten pro Nutzer und pro IP; bei 429 warten und später erneut versuchen.
• Erwachseneninhalte folgen den Einstellungen des jeweiligen Nutzers: Minderjährige und Nutzer mit aktivem Filter können explizite Titel weder sehen noch hinzufügen (adult_content_blocked).
• Nutzer können den Zugriff deiner App jederzeit unter Einstellungen → Anwendungen widerrufen.
• Der Katalog stellt mal_id und anilist_id bereit, wo bekannt — IDs einmal mappen und cachen.