Tips

REST APIでGETを使う3つの方法とその使い分けについて

目次

はじめに

固定リンクがコピーされました

kintoneのREST APIにおけるGETの使い方には、大きく分けると3つの方法があります。
それぞれ異なる特性があり、状況に応じて使い分けることができます。
本記事では、それらの方法と選び方のポイントについて解説します。

GETリクエストの3つの書き方

固定リンクがコピーされました

同じ「GET」リクエストでも、データ取得条件の指定については、いくつかの書き方があります。 kintoneのREST APIでは、主に次の3つの方法が使われます。

  1. URLにパラメーターを含める（クエリ文字列）
  2. GETリクエストのボディに条件を含める（GET + Body）
  3. POSTメソッド + X-HTTP-Method-Override: GETヘッダーを使用する

それでは、それぞれの方法について詳しく見ていきましょう。

方法1：URLにパラメーターを含める

固定リンクがコピーされました

最も一般的な方法は、GETリクエストのURLにクエリパラメーターを含める形式です。
REST APIにおいては、データの取得条件をURLの一部として指定することが多く、この方法は広く採用されています。

サンプル

固定リンクがコピーされました

アプリID「123」の中から「field1」に"example"を含むレコードを取得する場合。

項目 内容
HTTP メソッド GET
URL https://sample.cybozu.com/k/v1/records.json?app=123&query=field1%20like%20%22example%22
ヘッダー {
  "X-Cybozu-API-Token": "API_TOKEN"
}

メリット

固定リンクがコピーされました

  • シンプルで直感的な構文
  • 多くのHTTPクライアント・ツール（curl、ブラウザーなど）でそのまま使える
  • URLに全情報が含まれるため、キャッシュ対象になることもある

デメリット

固定リンクがコピーされました

  • URLの長さに制限がある（8KBまで）
  • 条件が複雑になると、URLが読みにくくなり、保守性も下がる
  • 特殊文字や日本語はURLエンコードが必要になる（例：スペース → %20）

向いているケース

固定リンクがコピーされました

  • 条件がシンプルで、短いURLで済む場合
  • curlやブラウザー、Postmanなどのツールで手軽に試したい場合

補足：クエリが長くなる場合の対応

固定リンクがコピーされました

複雑な条件やフィルターを多く含む場合は、URLから判別が難しくなります。
また、長さの制限値を超えた場合、「414 Request-URL Too Large」が発生し、リクエストの送信ができなくなります。
その場合は、後述の「方法3：POSTメソッド + X-HTTP-Method-Override: GETヘッダーを使う」を検討してください。
方法3：POST メソッド + X-HTTP-Method-Override: GET ヘッダーを使う

方法2：GETリクエストのボディに条件を含める

固定リンクがコピーされました

kintone REST APIでは、GETメソッドのリクエストボディに検索条件を含めることができます。
この方法を使えば、複雑なクエリや長い検索条件をURLではなくJSON形式のボディに記述して送信できるため、可読性や柔軟性の面でメリットがあります。

ただし、fetch、axios等のHTTPクライアント、kintone.proxy APIなど、GETメソッドでボディを送信することに対応していないものもあります。
そのため、使用するツールや環境によっては、この方法を利用できない場合があります。

サンプル

固定リンクがコピーされました

アプリID「123」の中から「field1」に"example"を含むレコードを取得する場合。

項目 内容
HTTP メソッド GET
URL https://sample.cybozu.com/k/v1/records.json
ヘッダー {
  "X-Cybozu-API-Token": "API_TOKEN",
  "Content-Type": "application/json"
}
ボディ {
  "app": 123,
  "query": "field1 like example"
}

メリット

固定リンクがコピーされました

  • URLの長さに制限されず、複雑な条件が記述できる
  • JSON形式で書けるため、構造が明確で編集しやすい

デメリット

固定リンクがコピーされました

  • fetch、axiosなどのHTTPクライアントや、kintone.proxy APIではGETメソッドでボディを送信する仕様に対応していない

向いているケース

固定リンクがコピーされました

  • クエリが複雑な場合でも、見やすさを保ちたい
  • 使用するHTTPクライアントが、GETメソッドでボディを含んだ送信ができることを確認している

補足：対応していない環境で使いたい場合

固定リンクがコピーされました

この方法は可読性が向上しますが、GETメソッドでボディを含める送信に対応していない、HTTPクライアント、API等があります。
また、GETリクエストでパラメーターをボディに含めることは、一般的な方法とは異なります。
そのため、現時点で送信できるHTTPクライアントでも、将来的に仕様変更により送信できなくなる可能性もあります。
将来的なリクエストエラーのリスクを減らす方法として、後述の「方法3：POSTメソッド + X-HTTP-Method-Override: GETヘッダーを使う」の利用を検討してください。
方法3：POSTメソッド + X-HTTP-Method-Override: GETヘッダーを使う

方法3：POSTメソッド + X-HTTP-Method-Override: GETヘッダーを使う

固定リンクがコピーされました

kintoneでのGETリクエストはURLにクエリを付けるか、ボディに条件を書く方法で送信されます。
しかし、使用するHTTPクライアント等が、GETメソッドでボディを使った送信をサポートしていない場合、方法2は使えないという制約があります。
そのような場合に使えるのが、HTTPヘッダーにX-HTTP-Method-Override:GETを付けて、実際にはPOSTメソッドで送信する方法です。

サンプル

固定リンクがコピーされました

アプリID「123」の中から「field1」に"example"を含むレコードを取得する場合。

項目 内容
HTTP メソッド POST
URL https://sample.cybozu.com/k/v1/records.json
ヘッダー {
  "X-Cybozu-API-Token": "API_TOKEN",
  "X-HTTP-Method-Override": "GET",
  "Content-Type": "application/json"
}
ボディ {
  "app": 123,
  "query": "field1 like example"
}

メリット

固定リンクがコピーされました

  • GETメソッドでボディを使った送信をサポートしていない場合でも、JSON形式で書けるため、構造が明確で編集しやすい

デメリット

固定リンクがコピーされました

  • 一部のプロキシやWAFでは制限される場合もある

向いているケース

固定リンクがコピーされました

  • GETメソッドでボディを使った送信ができないHTTPクライアント等を使用している
  • 条件が複雑などの理由で、クエリをJSONで柔軟に送りたい

おわりに

固定リンクがコピーされました

REST APIでレコードを取得する方法には、以下の3つのパターンが存在します。

方法 特徴 向いているケース
方法1
URLにパラメーターを含める		 最も一般的で直感的。
多くの環境で対応。		 条件がシンプルで、URLが短く収まる場合。検証やリンク共有にも便利。
方法2
GETメソッドのボディに条件を含める		 URLの長さ制限を回避でき、構造が明確で編集しやすいが、使用できない場合がある。 複雑な検索条件があり、使用するHTTPクライアント等がGETメソッドでボディを使った送信に対応している場合。
方法3
POSTメソッド + X-HTTP-Method-Override: GET ヘッダーを使う		 URLの長さ制限、GETメソッドでボディを使った送信ができない問題を回避できる手法。 方法1,方法2が使えない場合。
クエリをJSONで柔軟に送りたい場合。

それぞれの方法には長所と短所があるため、状況に応じて使い分けることが大切です。
最適な方法を選ぶことで、よりスムーズで安定したAPI実装につながります。
実際の開発でも、「どの方法が適しているか？」を考えながら柔軟に使い分けてみてください。