2021/06/04の勉強会で発表されたものです。

1. トビウオ、2021/06/04
Drupalにおける
JSON:APIの注意点
公式ドキュメントを読まないと掛かる落とし穴

2. JSON:APIとは？
• JSON形式で求めるデータ＋メタ情報を表現できるフォーマット
• 以前発表したスライドでも解説した
• 今回はDrupalに搭載されているJSON:APIについて解説

3. ハマりやすい注意点
1. X件要求してX件返ってくるとは限らない
2. 一度に取得できる件数に制限がある
3. 総件数を知る方法がない

4. 1. 返却される件数の問題
• 「端数、余りについての話だよね？」
• それとは別の理由でも起こりうる
• Drupalの権限(アクセス制限)に由来する問題

5. 1. 返却される件数の問題
id 記事名 種類
1 AAA 無料記事
2 BBB 無料記事
3 CCC プレミアム記事
4 DDD プレミアム記事
5 EEE 無料記事
6 FFF 無料記事
7 GGG 無料記事
• 「無料会員」ロールと「プレミア
ム会員」ロールがあり、後者のみ
プレミアム記事を参照する権限を
持っていたとする
• 無料会員アカウントがJSON:APIで
先頭5件を取得するよう要請すると
、id=3とid=4は取得できないので、
3件しか返ってこない

6. 2. 取得できる件数に制限がある問題
• 1. から、エンティティのデータを取得する際は、ア
クセス制限を考慮する必要がある
• ゆえに、一度に大量に取得すると強い負荷が掛かる
• そのため、一度には最大50件までしか返さないよう
に設定されている

7. 3. 総件数を取得できない問題
• これも1. 関連だが、「あるアカウントが取得できる
件数」を調べるだけでコストが高い
• そのため、総件数は分からないものとしてプログラ
ムを書く必要がある

8. データ取得のベストプラクティス
• 公式ドキュメントにサンプルコー
ドがある
• 「指定したリンクを頼りに、最大
X件のデータを取得する」関数に
ついてのもの
• 最大X件のデータと、「次のペー
ジ」に向けたリンクを返す

9. ベストプラクティスの詳解
• 本来、JSON:APIにはページング機能が備わっている
• page[offset]でオフセットを指定
• page[limit]で受信する最大件数を指定
• ただ、前述の事情により、page[limit]でX件指定しても、X件が返ってくると
は限らない
• そのため、次のX件を取得するには、nextを活用することになる

10. ベストプラクティスの詳解
• nextとは、JSON:APIでの戻り値におけるlinks.next部分のこと
• 上の青枠部分に、「next」「prev」「first」が含まれていることがある
• 「next」「prev」「first」は必須ではなく、どれか含まれないこともある
• 「nextがない」＝「次のページが存在しない(最後のページである)」

11. ベストプラクティスの詳解
つまり先ほどのサンプルを要約すると、次の3点となる。
1. データを取得し、バッファーにためておく
2. バッファーが必要数以上ならそれを返して終わり
3. まだ足りない場合は、nextから次のページの内容を見る
バッファーに十分貯まるか、nextがなくなるまで繰り返す

12. ベストプラクティスの注意点
• 公式ドキュメントより引用：
"next page" links in your HTML do not need to be correlated
to API pages! In fact, it's an indication that you might be doing it
"wrong" if they are.
• JSON:APIの戻り値における「next」と、Webページ上で表示するべき「next
」の内容は意味が異なっており、一対一対応させるようなコードを書くべき
ではないと書かれている。サンプルコードでもその辺りの対処はあった

13. 参考資料
• Pagination | JSON_API module | Drupal Wiki guide on drupal.org
• https://www.drupal.org/docs/core-modules-and-themes/core-
modules/jsonapi-module/pagination