Hoshika APIで作ろう

1. アプリを登録

どのHoshikaアカウントでもOAuth認証情報を作成できます: 設定 → アプリ.

• リダイレクトURIはhttps必須（開発用のhttp://localhostは可）。
• クライアントシークレットは一度だけ表示 — 安全に保管を。
• アカウントあたり最大5アプリ。

2. OAuth 2.0（認可コード + PKCE）

標準フロー: ユーザーを認可に送り、同意画面で承認、コードをトークンに交換。PKCE必須。

# 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 }

アクセストークンは24時間、リフレッシュトークンは90日有効。各API呼び出しに Authorization: Bearer で送信。

3. API

ベースURL https://hoshika.app/api/v1 — JSONの入出力。全レスポンスに ok を含み、エラーには安定した機械可読の 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. ルール

• レート制限はユーザー・IPごと。429が返ったらバックオフして後で再試行。
• アダルトコンテンツは各ユーザーの設定に従います: 未成年およびフィルター有効ユーザーは成人向け作品の閲覧・追加不可（adult_content_blocked）。
• ユーザーは 設定 → アプリ からいつでもアクセスを取り消せます。
• カタログエントリは既知の mal_id と anilist_id を公開 — IDマッピングは一度行いキャッシュを。