GETパラメータ：max指定時にロケーション情報の取得件数に差異がある

[kita7963]

Webex APIのロケーション一覧取得（List Locations）に関し、質問をさせて頂きます。
https://developer.webex.com/docs/api/v1/locations/list-locations

ロケーション139件を登録している環境に対し、GETパラメータ：max=100（APIドキュメントで提示されているデフォルト値の最大）を指定して、
ロケーション情報をAPI（List Locations）で確認したところ、
ControlHubで確認できる登録件数とAPIから得られた合計件数が一致しない事象を確認しました。
リクエスト送信にはPostmanを使用し、取得時間帯にControlHubおよびAPIによるロケーション登録は実施していないことを確認しています。

【取得結果】取得できたロケーション数：137件（2件欠損）

リクエストURL（1回目）
* https://webexapis.com/v1/locations?max=100
* データ件数：100件

リクエストURL（2回目）

※ リクエスト送信1回目のレスポンスヘッダーに含まれるLinkタグで提示されているページネーションURLを指定
* https://webexapis.com/v1/locations?max=100&cursor=*
* データ件数：37件

なお、

* GETパラメータ：maxを指定しないケース（GET https://webexapis.com/v1/locations）
* デフォルト値より下回るmax=80を指定したケース（https://webexapis.com/v1/locations?max=80）

の2ケースも合わせて確認したところ、この2ケースはControlHubとAPIのロケーション件数が一致しました。

これを踏まえて下記2点について確認させてください。

1. GETパラメータ：maxのデフォルト値について

APIドキュメントで提示されているGETパラメータ：maxのデフォルト値は100（Default: 100）と記載されていますが、
APIの仕様上、1リクエストに返却されるロケーション情報の最大値であるという理解でよろしいでしょうか？

※ maxを指定しないケースの場合、ページネーションが発生せず（レスポンスヘッダーにLinkタグが含まれず）、
1リクエストに100件を超過する全ロケーション情報が返却されたので確認させて頂きます。

https://developer.webex.com/docs/api/v1/locations/list-locations

2. GETパラメータ：max=100（デフォルト値）を指定した場合に欠損なく全ロケーション情報を返却可能か？

ページネーション発生時のテストや調整を理由に、1リクエストの取得件数は明示的に指定したいと考えています。
また、GETパラメータ：maxに、デフォルト値最大（100）を指定した場合でも、欠損なく全ロケーション情報が返却されることを期待しています。この事象が発生する考えられる要因や解決策がありましたら、ご教示いただけますと幸いです。

以上になります。
よろしくお願いいたします。

[Tohru Ohzono]

こんにちは。

Webex REST APIのpagingの仕様としては、以下のようになるはずです。

1. maxパラメータが指定されている場合は、最大その件数が１つのリクエスト、レスポンスで返される。
(maxの有効範囲は規定される場合がありそれを超えた場合は補正される。)
2. maxパラメータが指定されていない場合は、default値が適用され、最大その件数が１つのリクエスト、レスポンスで返される。
3. レスポンスのアイテム数が上記の(1)、(2)を超えている場合は、Linkヘッダーを利用して以降のアイテムが取得できる(これを繰り返してPagingして取得できる)。

ご報告いただいた内容を見た範囲では、該当のAPIの不具合の可能性が考えられます。
また上記(2)に該当する動作が該当APIに実装されていない可能性もあるかと思います。

原因特定がまだなので解決策の提案は難しいですが、より少ない数値をmaxに指定すると全件取得できているのであれば、
現状はそちらが一時的な解決策になる可能性は考えらえます。
ただし、maxの数字と実際のデータ数の関係性などで問題起こっているなら(カーソルの境界がずれているなど)、
この方法で必ず解決しない場合も考えられるので、まずは原因特定するのが確実かと思います。

ロケーションの該当機能の開発元と協議しようと思いますが、trackingId含めた詳細情報を求められる可能性が高いので、
改めてメールなどで相談させていただければと思います。

[Tohru Ohzono · Accepted solution]

お世話になっております。

コミュニティのダイレクトメッセージ機能でメッセージ送信したので、
内容ご確認いただければと思います。