レート制限のドキュメントに「スロットリング制限がかかる状態が長時間続かないようリクエスト送信を制御」と記載されている
2024年5月14日に導入された、プラットフォーム API 共通のレート制限の API クライアントに期待する運用方法について質問です。
API ドキュメントには以下のような記述があります。
> スロットリング制限がかかる状態が長時間続かないようリクエスト送信を制御してください。
> 一定期間内に発生したスロットリング制限エラーが多い場合、リクエスト拒否を行う可能性があります。
https://developers.smaregi.dev/apidoc/common/#section/%E3%83%AC%E3%83%BC%E3%83%88%E5%88%B6%E9%99%90
この文面を字面通りに解釈すると、プラットフォームAPIにレート制限が存在するかどうかに関わらず、APIクライアント（各スマレジアプリ）が自身の責任においてリクエスト送信の流量制御を行う必要があるように思えます。
2024年5月14日まではプラットフォームAPIにレート制限はありませんでしたから、（本来APIクライアントの責務ではない）流量制御の仕組み自体は各アプリで持ち合わせていると思いますので、この条項を遵守することは難しくないと思われます。
しかしながら、APIクライアントが流量制御を行わざるを得ないのであれば、APIサーバ（プラットフォームAPI）のレート制限には存在する価値がないことになってしまいます。
本記述はどのように解釈するのが適切でしょうか？プラットフォームAPIが期待する実際的な利用方法をご教示いただけると幸いです。
ベストアンサー
-
スマレジに限らず、APIクライアント側でリクエスト量の制御や、制限超過時の再試行処理の実装をしていただくことを推奨しております。
はい、先だってのコメントの通り、スマレジさんのプラットフォームとしてのスタンス・規約は十分に理解した上で遵守して用います。
「API クライアントがレート制限の実装責任を負うような想定を廃して欲しい」というコメントについては、そもそも利用規約で禁じている利用方法であり、フィードバックも行わないというご回答ですね。承知しました。
「実装責任を負わせるならアルゴリズムを公開して欲しい」というコメントについても、開発チームの方にフィードバック頂くのは難しいですか？
なお「スマレジに限らず」とのことですので、参考までに他社さんの事例を挙げると、
Shopifyさん https://shopify.dev/docs/api/usage/rate-limits はアルゴリズムも含めて公開されています。
LINEさん https://developers.worksmobile.com/jp/docs/rate-limits#how-to-check-ratelimit は「Rate Limit は、ピーク時を想定した Limit 値です。30 分以上連続して API 呼び出しを行う場合は、Limit 値の半分以下を目安に使用してください。」と記述されており、先だって私たちがご質問さしあげたウィンドウをまたぐ場合の疑問を自己解決できる内容になっています
重ねてお伝えしますが、私たちはAPI利用者として、スマレジさんのプラットフォームとしてのスタンス・規約は十分に理解した上で、遵守して開発しています。その上で、プラットフォームの直接のユーザーとして、より使いやすい（意図の汲み取りやすい）ドキュメンテーションをして頂けるよう、現場の方にフィードバックをお願いしている次第です。
上記フィードバックも難しいということであれば、そのように理解します。ご回答頂けますと幸いです。
答え
一般的に、APIの提供者はサーバの負荷を管理し、公平なサービス提供を維持するためにレート制限を設けることがあります。レート制限の目的は、過剰なリクエストがシステム全体に悪影響を与えることを防ぐことです。
2024年5月14日以降、スマレジのプラットフォームAPIにもレート制限を実施し、流量制御を行います。これまでAPIクライアント側で行っていた流量制限は、あくまでAPI提供の安定化のために都度協力をお願いする形でした。しかし今後は、レート制限に抵触しないように流量制御を行っていただく必要があります。
APIクライアントは、リクエスト量がレート制限以下となるよう責任を持ちます。一方、スマレジプラットフォームAPIは、レート制限の実施によりサービスの安定提供について責任を持ちます。
API提供者の責任でレート制限を実施することで、より安定したサーバの稼働を実現します。また、一部のクライアントが過度にリソースを消費することを防ぎ、システム全体のパフォーマンス維持を実現します。
スマレジ 宮地様
お忙しい中、ご回答頂きありがとうございます。
> APIクライアントは、リクエスト量がレート制限以下となるよう責任を持ちます。
> 一方、スマレジプラットフォームAPIは、レート制限の実施によりサービスの安定提供について責任を持ちます。
まさにこの点についてご回答を頂きたく、質問を投稿しておりました。
APIクライアントにもリクエスト量を制御する責任があるというのは奇妙に聞こえますが、スマレジさんのお考えとしてはそのようなものであると理解しました。
すると、「責任を果たしているAPIクライアント」がプラットフォーム API を使うには、「プラットフォームAPIのレート制限」機能の存在如何に関わらず、従来「協力」として実装していたレート制限を、引き続き保持し続ける必要があるということですね。
承知しました。
そうしますと、プラットフォームとして推奨する「レート制限」のアルゴリズムを指定して頂く必要があると考えますが、いかがでしょうか？
現状の「X回/秒」という定義では、以下のようなリクエストをどう集計すべきかがわかりません。
GET 2024-05-14T00:00:00.200Z
GET 2024-05-14T00:00:00.500Z
GET 2024-05-14T00:00:01.000Z
このようなリクエスト群は、「2回/秒（00:00:00.000 ~ 00:00:01.000 で集計）」と「3回/秒（00:00:00.200 ~ 00:00:01.200 で集計）」のいずれと捉えるべきでしょうか？
推奨するアルゴリズムでご教示頂けますと分かりやすく助かります。
レート制限アルゴリズムに関する詳細については、サービスの性能や安定性を向上させるため将来的に変更する可能性があり、非公開としております。現在公開している「X回/秒」形式の基本的なポリシーを遵守いただければ幸いです。
具体的なポリシーの内容は以下の通りです：
https://developers.smaregi.dev/apidoc/common/#section/%E3%83%AC%E3%83%BC%E3%83%88%E5%88%B6%E9%99%90
ご理解とご協力のほど、よろしくお願い申し上げます。
素早く反応頂き、ありがとうございます。
このようなリクエスト群は、「2回/秒（00:00:00.000 ~ 00:00:01.000 で集計）」と「3回/秒（00:00:00.200 ~ 00:00:01.200 で集計）」のいずれと捉えるべきでしょうか？
この質問については、どのような回答を頂いたと解釈をすればよいでしょうか？
レート制限アルゴリズムの詳細は非公開のため回答出来ない、が回答内容です。
APIクライアントの実装においてはどのアルゴリズムにおいても仕様書記載の制限を遵守いただければ幸いです。
なるほど、承知しました。
アルゴリズムが非公開ということはウィンドウの存在有無、存在するとしてどのウィンドウを取るべきかも非公開ということになりそうですね。
仕様書記載の制限（参照系 50回/秒・更新系 20回/秒）を安全に遵守するには、スマレジさんがどのアルゴリズムを採用していても安全であろう、参照系 25回/秒・更新系 10回/秒 を上限として実装する必要があると理解しました。
上記の状況は理解したのでそのように用いますが、API の利用者としては使いづらい仕様及びドキュメントとなっているという感想を持ちました。
API クライアントがレート制限の実装責任を負うような想定を廃して欲しい、もしくは実装責任を負わせるならアルゴリズムを公開して欲しい、左記二点を、開発チームの方にフィードバック頂けますか？
利用規約( https://smaregi.jp/legal/terms_developers.php )にある通り、下記の行為は禁止事項とさせていただいております。
>14. 当社による本サービスの提供、又はスマレジ・デベロッパーズの運営を妨害し、これらに支障を与える行為（開発者のアプリにおいては、当該アプリの動作が本サービス又はスマレジ・デベロッパーズの運営に支障をきたす場合）
上記規約では、APIクライアントがスマレジのAPIに支障を与える行為を禁止しておりますので、クライアント側では適切なリクエスト量となるよう制御する責任が発生しております。
スマレジに限らず、APIを提供している会社の多くは利用規約に上記同様の記載を行っており、APIクライアント側でリクエスト量の制御や、制限超過時の再試行処理の実装をしていただくことを推奨しております。
レート制限に抵触した場合は仕様書記載の通り、レート制限エラーである429エラーを返しますので、再試行処理をしていただければと思います。
スマレジ・プラットフォームAPI 共通仕様書: https://developers.smaregi.dev/apidoc/common/#section/%E3%83%AC%E3%83%BC%E3%83%88%E5%88%B6%E9%99%90
また、レート制限のしきい値を大幅に超えるリクエストを送信し、他のユーザーへのAPI提供に影響が出ると判断した場合は一時的に通信を遮断させていただく可能性もありますのでご認識ください。
API提供者とAPI利用者の関係においてサーバーの安定性を保ち、全てのユーザーに対して公平なリソース配分を保証するための重要な措置ですので、ご理解いただければ幸いです。
ありがとうございます！