『Web API デザインの鉄則』第1章 読書メモ

WEB+DB PRESS Vol.82

第1特集の『Web API デザインの鉄則』が興味深い内容だったので、要約しておきます。

Web APIとは何か

  • HTTPないしはHTTPSプロトコルによって通信が行われる
  • 特定のHTTPメソッドを用いてアクセスできる
  • 特定のURIにおいて提供される
  • URIのクエリパラメータやHTTPリクエストボディに一貫した呼び出し方の決まりがある
  • HTTPレスポンスのヘッダやボディの表現方法に一定の決まりがある

なぜWeb APIを使うのか

  • HTTPやHTTPSといったポピュラーなネットワークプロトコル経由でデータをやりとりできる
  • インタフェースを制約することで、アプリケーション連携が壊れないように設計できる
  • 同期的にデータをやりとりできる

※Web APIのアーキテクチャスタイルにはREST、RPC、SOAPなどがあるが、この記事では主にREST、補足的にRPCを用いている。

RESTスタイルの特徴:ROA

※ROA(Resource Oriented Architecture)

ROAの4つの概念:

  • リソース
  • URI
  • 表現(Representation)
  • リンク

リソースとは、データとして表現できるもの。
ROAにおいては、リソースはURIで識別する。
また、リソースは様々な表現を取りうる。たとえば、同じデータでもHTML/XML/JSONなど様々なフォーマットで表現できる。
リソースとリソースを結ぶのがリンク。

ROAの4つの特徴

アドレス可能性(Addresability)
提供する情報がURIを通して表現できること。
ステートレス性(Stateless)
APIリクエストのためのHTTPリクエストがすべて分離・独立していること。
接続性(Connectability)
リソースが別のリソースとの関連を示すリンクをもちうること。
統一インタフェース(Uniform Interface)
リソースの操作がHTTPメソッドという共通したインターフェースを持つこと。

RPCスタイルの特徴

Remote Procedure Callの名前の通り、リモートホストの関数を呼び出すようなスタイル。
一般的なプログラミングの考え方をそのまま応用しやすい。

RESTにするかRPCにするか

RESTは設計時の制約が強い。さまざまな個所を異なる人が設計したとしても一定の一貫性を担保できる。
RPCは柔軟性が高く中央集権的。エンドポイントはL7で分散できない。

RESTが向いている場合

  • 公開APIなど、不特定多数のクライアントがAPIを用いる場合
  • 複数のエンジニアがAPIの設計をする場合
  • L7で分散したい場合

RPCが向いている場合

  • クライアントが社内に限定されていたり、SDKのような形で必ずラップされている場合
  • 限定されたエンジニアがAPIの設計をする場合

多くの場合、RESTを選択するべき。

RESTful APIをリリースするまでに決めなければならないこと

  1. 認可(Authorization)方式の決定
  2. リソース設計
  3. インタフェース設計
  4. エラー表現
  5. ドキュメント

内容的には、『Webを支える技術』を実装寄りにして、濃縮した感じ。

Webを支える技術 -HTTP、URI、HTML、そしてREST (WEB+DB PRESS plus)

コメントを残す