「WebAPI デザインの鉄則」を読みました

tl;dr

WEB+DB PRESS vol.82の「WebAPI デザインの鉄則」の3、4章を読みました。

:arrow_down: は、3、4章の目次です。

3. インターフェース設計
4. エラー表現とドキュメント

新しく知ったこと

次の2つのことを新しく知りました。

  1. POSTメソッドとPUTメソッドの使い分け
  2. Web APIのエラー設計の指針

POSTメソッドとPUTメソッドの使い分け

新規リソースを作成する場合についてです。次の違いがあります。

  • POSTメソッドは、リソースのURLの指定する必要がない。
  • PUTメソッドは、リソースのURLの指定する必要がある。

PUTメソッドを使用する場合、リソースのURLを指定する必要があるため、サーバーの実装の詳細を知っている必要があります。また、一般的に新規リソースの作成はPOSTメソッドが使用されるらしいです。

Web APIのエラー設計の指針

この章のお気に入りの点は、なぜこのレスポンスを返すのか理由が記載されている点です。

例を示します。 認証がかかっているリソースにアクセスする場合を考えます。通常認証に失敗した場合、403 Forbiddenがリターンされます。 この時、クライアントは、リソースが存在していることが分かります。 要件によっては、リソースの存在をクライアントに知られたくないことがあります。その場合は、404 Not Foundをリターンします。

このように、なぜこのレスポンスを返すのかが解説されているため、すぐに役立ちそうです。

まとめ

本特集では、REST APIの思想からWeb APIのインターフェース設計、クライアントへ返すステータスコードについて記載されていました。 そのため、読了後にWeb APIの設計・実装の下地が出来ると思います。