Zenn
🙆

良いAPIとは何か

2022/10/02に公開
API
tech

現場で役立つシステム設計を読んだのでメモ

用途が明確で単純な小さなwebAPIは、仕様の検討も実装も検証も簡単。
そのようなWebAPIのの設計原則は以下。

  • 登録と参照を分ける
  • リソース(データ)のかたまりの単位を分ける

登録と参照は別のAPIにする

例えば、指定席の予約APIを作るとする。
予約がPOSTされた時に、予約した詳細内容を画面に表示するのが一般的。
この予約機能を実現する方法は下記2種類。

  • POSTのレスポンスとして、予約の詳細内容を返す
  • POSTのレスポンスはその予約番号だけを返し、その予約番号を元に詳細内容をGETする

前者は、WebAPIではなくWebサービスの発想。
アプリケーションを組み立てるための部品としては後者のように登録のAPIと参照のAPIを別々にしていた方が柔軟にアプリケーションを組み立てることができる。

予約の結果の参照方法や応答内容に変更があっても、予約登録のAPIに影響しない。参照のAPIを登録のAPIへの影響を心配せずに修正や拡張ができる。
参照と登録を別のAPIにするのは、関心ごとを分離し、分離し、プログラムの記述をわかりやすくシンプルにする設計の基本原則

リソースの単位を分ける

次のような会員情報の登録と参照を行うWebAPIを考えてみる。

  • 氏名
  • 性別
  • 生年月日
  • 連絡先
  • 住所

この設計では、氏名だけが必要な場合でも、毎回、性別/生年月日/住所を取得することになる。
そのやり方ではなく、用途別に小さな単位のデータを受け取るAPIを提供する方法がある。

GET members/1234/name 名前を返す
GET members/1234/gender 性別を返す
GET members/1234/dayOfBirth 生年月日を返す
GET GET members/1234/contactMethods 電話番号とメールアドレスを返す
GET members/1234/address 住所を返す

情報を変更する場合も、毎回全ての情報を更新するのはいいAPIではない。変更が起きそうなリソースに限定したAPIを提供する。

POST members/1234/contactMethods/telephone 電話番号の変更
POST members/1234/address 住所の変更

対象とするリソースの必要な最小の単位に分けることを重視して設計する。

使い方を限定した用途が明確なAPIを組み合わせる方が、多様な機能を実現しやすくなる。そういう小さい単位のAPIに分けておけば、特定のAPIに修正や変更があっても、他のAPIは早く安定する。修正や変更がダラダラと続き、なかなか安定しないのは、より小さな単位に分割すべき明らかな兆候。

WebAPIのバージョン管理

URIにバージョン番号を入れるという考え方がある。

http://api.example.com/v1/members

しかし、プログラミングの部品を提供することを重視する重視するWebAPIでは、全体のバージョン管理を行うことにあまり意味はない。
リソースを小さな単位に切り分けるAPIでは、新たな小さなAPIの追加が中心になる。その場合、既存のAPIには何も影響しないので、APIバージョンとして管理する意味はない。現在のAPIのセットが有効な唯一のバージョンとして提供し、利用すれば良い。

Discussion