ぶうううん's Cafe

どうにかこうにか。備忘録に近い。

RESTful APIについて

Web

RESTful APIの前提知識を盛大に勘違いしていたので、戒めとして書いておきます。

RESTとは

  • アーキテクチャ上の成約の集合である。
  • RESTで情報をやり取りする際はHTTP上で、以下の形式で送受信を行う。
  • RESTfulでは、以下の内容を満たす必要がある。
    • クライアント、サーバ、リソースからなるクライアント/サーバアーキテクチャである。
    • ステートレスなクライアント/サーバ通信。セッション状態に関する情報はサーバではなくクライアントが保持する。HTTPはステートレスなのでRESTfulと相性が良い。
    • キャッシュ可能なデータである。
    • 以下の要件を満たす、コンポーネント間で統一されたインタフェースである。
      • 要求されるリソースは識別可能であり、クライアントに返却される表現とは切り離されている。
      • クライアントが受け取る表現には操作に十分な情報が含まれており、クライアントはその表現を用いてリソースを操作可能である。
      • サーバからのレスポンスには、クライアントがレスポンスを処理するために必要十分な情報が含まれている。
      • ハイパーテキスト/ハイパーメディアが利用可能である。
    • 要求された情報の取得に関係するWAFやロードバランサなどのサーバを、クライアントからは参照できないようにする階層化システムである。
    • 実行可能コードを要求されたときに、サーバからクライアントにコードを送信するコードオンデマンド機能が利用できる。(これに関しては任意である)

私の勘違いと正しいAPIエンドポイント設計

  • APIエンドポイントについて、HTTPリクエストメソッドそれぞれに対応して、1つ1つエンドポイントを作成するものだと思っていた。つまり、HTTP GETリクエストに対応するAPIエンドポイント、HTTP POSTリクエストに対応するAPIエンドポイントといった形で分けて作成し、以下のように HTTPリクエストメソッドとAPIエンドポイントは1対1で対応するものだと思っていた。
    • https://hogehoge.com/users_get
    • https://hogehoge.com/users_create
    • ...
  • APIエンドポイントはCRUD単位などでまとめて作成するものであり、応答するAPIエンドポイントをHTTPリクエストメソッドごとにそれぞれ分けて作成すべきではない。
  • サーバが処理すべき内容はHTTPリクエストメソッドで判別すべきである。
  • 本来は次のように、 HTTPリクエストメソッドとAPIエンドポイントの関係は多対1である。
    • https://hogehoge.com/users
    • https://hogehoge.com/users/012345...

References