Backlog APIのレート制限ヘッダー捕捉とget_rate_limit操作を追加する

[igapyon]

背景

Backlog APIのレート制限は、APIキー単位ではなくユーザー単位で適用され、read、update、search、icon の種別ごとに管理される。各APIレスポンスには次のヘッダーが付与される。

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

現在の backlog-api v0.3.3は backlog-js を利用しているが、成功レスポンスはverbose層へ到達する前に本文へ変換されるため、レスポンスヘッダーと成功時のHTTPステータスを参照できない。一方、内部SDKには getRateLimit() が存在するものの、公開している58操作には get_rate_limit が含まれていない。

通信層とクライアント生成に変更が必要となるため、#10 の識別情報・実行メタデータ拡充とは分けて扱う。

実装方針

次の二段階で実装する。優先順位は、各アクセスのレスポンスヘッダー捕捉、明示的な get_rate_limit 操作の順とする。

1. 各APIアクセスのレート制限ヘッダーを捕捉する

• Backlogクライアント生成時にカスタム fetch を注入し、Response を受け取った直後に許可した3ヘッダーだけを読み取る
• 値をアクセス単位のverbose成功・失敗イベントへ構造化して追加する
• X-RateLimit-Limit と X-RateLimit-Remaining は整数として検証する
• X-RateLimit-Reset はUTCのUNIX秒からISO 8601日時へ変換する
• 欠損値や不正値は出力しない
• 並行実行時に、別の組織、クライアント、APIアクセスの値が混ざらない設計にする
• URL、APIキー、本文、エラー本文、許可していないレスポンスヘッダーは記録しない
• レスポンス本文を不要に消費または複製しない
• 実際の Response から取得できる場合のみ httpStatus を出力し、成功時の 200 などを推測しない

verboseイベントの表示例:

{
  "rateLimit": {
    "limit": 600,
    "remaining": 599,
    "resetAt": "2026-07-22T13:30:00.000Z"
  }
}

リクエスト種別は、実際のAPI操作との対応を明示できる場合だけ出力する。HTTPメソッドなどから不確実な推測はしない。

2. get_rate_limit 操作を追加する

• SDKの getRateLimit() を利用するREAD操作として公開する
• read、update、search、icon の各種別について、上限、残数、リセット時刻を返す
• 既存の上流58操作とは別のNode CLI独自操作であることをトレース情報に明記する
• 操作一覧、対応表、--help、README、開発者向け文書、テストを更新する
• レート制限情報の取得自体もAPIアクセスを1回消費することを説明する
• 複数組織構成では既存の組織選択ルールを適用する

レート制限の管理単位

公式仕様で明記されている単位は「ユーザー別」であり、APIキー別ではない。同一ユーザーが複数のAPIキーを利用しても制限枠は共有される。

スペースをまたいだ制限枠の共有・分離は公式資料に明記されていないため、実運用上は次の単位で保守的に管理する。

対象スペース × 認証ユーザー × リクエスト種別

これは公式仕様ではなく運用上の推定であることを文書に明記し、APIキー単位とは説明しない。

受け入れ条件

ヘッダー捕捉

• 成功時と失敗時のverboseイベントに、実際に取得できたレート制限情報が含まれる
• resetAt がUNIX秒から正しいUTC ISO日時へ変換される
• ヘッダーの欠損値と不正値が安全に省略される
• 並行実行テストでアクセス間の値が混ざらない
• URL、APIキー、リクエスト本文、レスポンス本文、エラー本文、許可していないヘッダーを出力しない
• 通常のstdout出力を変更しない
• --verbose が無効な場合のstderr出力を変更しない
• READ、CREATE、UPDATE、DELETEの代表的な操作でテストする

get_rate_limit

• デフォルト組織と名前付き組織の両方で実行できる
• read、update、search、icon の4種別を返す
• READ権限で利用できる
• Node CLI独自操作であり、上流58操作には含まれないことが対応表から分かる
• APIアクセスを1回消費することと、ユーザー単位の制限であることがヘルプと文書から分かる

品質確認

• 型チェック、ユニットテスト、CLIスモークテストが成功する
• 実際のBacklog環境で、少なくとも1回はレスポンスヘッダー捕捉と get_rate_limit を確認する

参考資料

• Backlog API レート制限
• レート制限情報の取得