Backlogから、APIのレート制限を導入するというお知らせが届きました。

詳細はリンク先に記載されていますが、概要をまとめると、

APIに対して、 1分間あたりのリクエスト数制限 を導入する。
2021年1月25日以降に作成されたスペースには即導入、既存スペースは2021年7月末から制限 が適用される。
制限はユーザ単位、APIの種類単位で設定される。
- APIキー単位ではなくユーザ単位で制限 され、同一ユーザ複数APIキーを使用している場合は相互に影響を受ける。
- 個別のAPI単位ではなくAPI種類で制限 され、有料プランの場合は読み込みが 600回/分、更新が 150回/分、検索が 150回/分、アイコン取得 60回/分。
制限を超えた場合のレスポンスコードは 429 : Too Many Requests 。

そして、既存スペースが影響を受けるかどうかの確認手段としては

各APIのレスポンスヘッダ（ X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset ）での確認
レート上限の取得API（ /api/v2/rateLimit ）

が提供されているので、それぞれ試してみました。

1) APIのレスポンスで確認

各APIに対して、レスポンスヘッダに項目が追加されています。

X-RateLimit-Limit : 1分間に受付可能な最大リクエスト数
X-RateLimit-Remaining : X-RateLimit-Resetの時刻までに受付可能な残りリクエスト数
X-RateLimit-Reset : リクエスト数の計測がリセットされる時刻（UNIX時間）

例として、プロジェクト一覧取得のAPIを実行してみると、以下のように結果が取得できました。

$ curl -s -D - https://＜スペース名＞.backlog.jp/api/v2/projects?apiKey=＜確認対象のAPIキー＞ \
  | grep X-RateLimit
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1615357273

このAPIを実行したことにより、残りリクエスト数が 1減っていることが確認できます。

レート制限に対する対応としては、これらを確認してのリクエスト数の調整、あるいは429エラーが返った場合のリトライ等の対応が必要となります。

2) レート上限の取得API（ /api/v2/rateLimit ）で確認

レート上限を取得するAPI : /api/v2/rateLimit も別に提供されています。

$ curl -s https://＜スペース名＞.backlog.jp/api/v2/rateLimit?apiKey=＜確認対象のAPIキー＞ \
  | jq -r .
{
  "rateLimit": {
    "read": {
      "limit": 600,
      "remaining": 598,
      "reset": 1615357067
    },
    "update": {
      "limit": 150,
      "remaining": 150,
      "reset": 1615357016
    },
    "search": {
      "limit": 150,
      "remaining": 150,
      "reset": 1615357016
    },
    "icon": {
      "limit": 60,
      "remaining": 60,
      "reset": 1615357016
    }
  }
}

結果にあるように、API種類ごとの制限がまとめて取得できます。下記は jqのフィルタ条件を追加し、残りリクエスト数のリストを取得する例です。

$ curl -s https://＜スペース名＞.backlog.jp/api/v2/rateLimit?apiKey=＜確認対象のAPIキー＞ \
  | jq -r '.rateLimit | [ .read.remaining , .update.remaining , .search.remaining , .icon.remaining ] | @csv'
599,150,150,60

Backlog APIには各種のAPIライブラリもありますが、レスポンスヘッダの対応がまだされていないものもあるようです。

とり急ぎAPIを使った既存処理への影響を確認するためには、こちらのAPIを定期的(10秒間隔とか)に実行して傾向を見る方法も考えられます。ただし例にあったように、このAPI自身が参照系のリクエスト数を消費するので、そこは考慮に入れる必要があります。

参考資料