はじめに
APIを設計する際に「これGETにすべき？POSTにすべき」と思う場面はないでしょうか。
ざっくりなイメージとして「GETはデータの取得」「POSTはデータの作成」くらいにしか思っていなかった自分がいます。
では「外部APIと通信するAPIはGET or POST？」「PDFのエクスポートはGET or POST？」
この辺りで悩むケースがポツポツあったので整理します！
まずはMDNのドキュメントを読んでみる
HTTP リクエストのメソッドと、それぞれの安全性、キャッシュ可否、べき等静による分類を示します。
| メソッド | 安全性 | 冪等性 | キャッシュ |
|---|---|---|---|
| GET | あり | あり | 可 |
| POST | なし | なし | 条件付き* |
*レスポンスに鮮度情報と、一致する Content-Location ヘッダーが明示的に含まれている場合、キャッシュ可能です
なるほど、安全性、冪等性、キャッシュが判断基準になりそうですね！
それぞれ詳しく見ていきます。
安全性
HTTP メソッドが安全であるとは、その HTTP メソッドがサーバーの状態を変更しないということです。言い換えれば、読み取り専用操作につながる場合、メソッドは安全です。
「サーバーの状態を変更しない」 というところがポイントですね！
サーバーの状態というのはDBのデータ、負荷状況などを指します。
安全なメソッドはサーバーに害を及ぼさない（負荷をかけたり、DBのデータを更新したりしない）ものを指します。
冪等性
単一のリクエストを送信した際のサーバーへの意図された効果が、同一のリクエストを複数回送信した場合の効果と同一であることです。
つまり、同じリクエストを送ったら必ず同じ結果が返ってくる状態を指します
キャッシュ
キャッシュ可能なレスポンス（応答）とは、キャッシュすることが可能な HTTP レスポンスで、後で取り出して使用するために格納され、サーバーへの新しいリクエスト（要求）を節約します。 すべての HTTP レスポンスがキャッシュされるわけではなく、キャッシュされる HTTP レスポンスには次の制約があります。
リクエストで使用されるメソッドは、それ自体がキャッシュ可能です
レスポンスのステータスコードはアプリケーションキャッシュによって認識され、キャッシュ可能と見なされている場合。キャッシュ可能なステータスコードは、 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501 です。
レスポンスに特定のヘッダー、たとえば Cache-Control にキャッシュを禁止する値がついたものがない場合。
一言で言うと、リクエストを送る時、毎回サーバーからデータを取得するのを節約するための仕組みですね！
具体例集：よく迷うGET / POSTのケース
外部APIと通信するAPI
結論から言うと、外部APIと通信しているかどうかは、GET / POSTの判断基準ではありません。
HTTPメソッドは
「このAPIを叩いたときに、自分のサーバーの状態がどう変わるか」
で決めます。
例えば天気予報を取得する場合に外部の天気APIを呼んで結果をそのまま返すだけであれば、DBへの書き込みは発生しないため、GETが適切となります。
外部APIの結果をDB保存する場合はPOSTが適切になります
PDFを作成・取得するAPI
PDFは特に迷いやすいポイントですが、サーバー状態は変わらないのであればGETが適切になります。
ただし、計算コストが高くサーバーに負荷がかかる、毎回生成結果が変わる可能性がある場合はPOSTが適切になります
おわりに
最後まで読んでいただきありがとうございます！
こればではよく「副作用がある場合はPOST」みたいに聞いていたのですが、副作用ってなんやねん！をもう少し丁寧に整理したかったので良い機会になりました！