HTTPメソッドを正しく使いたいという話

お仕事
2024.12.26

他人が作成したAPIを利用する際に発生した問題

2024年も他の方が作成したAPIを利用する機会が数多くありましたが、今年も以下のようなAPIに出会うことがありました。

  • GETメソッドなのに、クエリパラメータが存在せず、リクエストボディのみが存在している。
  • POSTメソッドなのに、多数のクエリパラメータが付いている。
  • 情報を取得する目的のAPIなのに、POSTメソッドを利用している。

※ちなみに、いずれもHTML4.0ではありません。

今までは「よくあることだな」と流していましたが、この機会に上記の事象が発生する背景を考察（想像）し、HTTPメソッドについて再度確認をしたいと思いました。

問題となるAPIが誕生した背景

あくまで、カモネギ個人の想像ですが、おそらく以下のいずれかの経緯で誕生したのでしょう。

GETメソッドなのに、クエリパラメータが存在せず、リクエストボディのみが存在している。

  1. APIを初めて作成した時点ではクエリパラメータだけであった。しかし、改修を重ねるうちにリクエストパラメータに秘匿情報を含める必要が出てきたため、リクエストボディに変更した。
  2. 深く考えずにAPIを作成した。

POSTメソッドなのに、多数のクエリパラメータが付いている。

  1. GETメソッドのAPIをコピーして改修したが、忙しくてクエリパラメータのままにしてしまい、忙しくてソースコードレビューもほぼされていない。
  2. 深く考えずにAPIを作成した。

情報を取得する目的のAPIなのに、POSTメソッドを利用している。

  1. POSTであれば何でもできそうだし、しかも今は忙しから、とりあえず全てPOSTにしておこう！
  2. 深く考えずにAPIを作成した。

人は思わぬ行動をするので、上記以外の背景が思い浮かびませんでしたが、カモネギの経験上こんな感じかなと想像しています。

とはいえ、HTTPメソッドについてある程度理解していれば、開発段階で違和感に気が付くはずです。

そのため、各HTTPメソッドについて再度確認をしておこうと思います。

HTTPメソッドの用途

各メソッドの用途と最も推奨されるパラメータを、以下にまとめました。

HTTPメソッド用途最も推奨されるパラメータ
GETリソースの取得クエリパラメータ
POSTリソースの新規登録リクエストボディ
PUTリソースの更新リクエストボディ
DELETEリソースの削除パスパラメータ
PATCHリソースの一部変更リクエストボディ
HEADリソースのメタ情報の取得ー

用途にあったHTTPメソッドとパラメータを利用していきたいものです。

所感

とはいえ、実際にAPIを開発する側の事情としては、忙しくてとりあえずで作成したものがそのまま本番環境に乗ってしまったり、過去の技術負債を解消できずにいたりと、色々と理由はあるとは思います。

一度本番環境で動作してしまうと、そう簡単には変更をしづらくなるので、やはり最初が肝心だなと痛感する一年でした。

参考：
水野貴明. “Web API: The Good Parts”. O’REILLY, 2014.
https://qiita.com/sakuraya/items/6f1030279a747bcce648

以上

タイトルとURLをコピーしました