日頃Web APIの設計や実装に携わることが多く、とはいえまだまだ未熟だなと自身に感じる部分も多く、何が足りていないのかを知りたいような気持ちがあった。そんなときにこの書籍に出会えた。
日本語で読めるWeb APIに関する書籍だと、Web API The Good Partsが有名。あの書籍も良かったが、出た当時からそれなりに時間が経ってしまったのと、あの書籍の記載内容は少し薄い部分もあり、もう少し何か別のものを、という気持ちがあったが、この書籍はまさにそこを満たすようなものだった。
Web APIの名前付けやリソースの切り方、まではいいとして、それを実際にユーザーに使ってもらうときの権限設定の仕方は実務上非常に重要な関心事になる。
セキュアにするためにどのように区分していくといいのかを示しているのが次の図。
出所：(Kindle Location 4584)
また、読み進めていくと、センシティブなデータをどのように扱うかについて記述があった。
参照権限がないユーザーが見にきた場合に、Permissionが足りない、のように返すと、そのエンドポイントリソースが存在していることを認めることになってしまうので避けるべき、というのは一般的な話ではあって、例えばGitHubなんかは見る権限がない状態でアクセスすると404 Not Foundを返す。
このカードを読み取るためのパーミッションがエンドユーザーに割り当てられていないことを意味する。状況によっては、この最後のエラーは情報漏洩と見なされる可能性がある。 (Kindle Locations 5006-5008)
ただ、そのリソースは存在するのに404というのは適切なんだろうか？という気持ちはあった。
が、この書籍の中でその回答は得られた。
要するに、その権限のないユーザーの「コンテキスト」においてはNot Foundだということ。ユーザー（コンシューマー）視点で捉えると理解ができる。
同じような話で、/accountsというエンドポイントを指した際の結果がコンテキストによって異なる例が次の図。
出所：(Kindle Location 4753)
なんとなく自分の場合、リソースに対する考えが強すぎるのか、
/accounts/C1を用意するとか/accounts?id=C1を用意するとかの対応の考えてしまう。
言い換えると、同じエンドポイントに同じパラメーターでアクセスしたら同じ結果が返ってくることを期待するべき、と思っていた。
が、ユーザーコンテキストというものを一緒に考えると、そのコンテキストがフィルターになって返す内容が変わる、ということもあるのだと理解できた。
同じエンドポイントだからと言って同じ結果を返さなくていいのだよね。
それにid=C1にアクセスした人がC1の権限を持っているかを別途確認しないといけないことを考えると、サーバーサイドの手数という点で見ても大差はなさそう。
それに書籍内で触れられていたけど、/accounts?id=C1のように記録してしまうのがいいことかどうかという問題もある。
C1がセンシティブな情報だったらその扱いを適切にしなければいけない。なんでもパラメーターにしていいわけではないんだね。（まあそもそも設計原則的にクエリパラメーターはフィルタリング用途などに使うのが普通だからなんでもパラメーターにするわけはないけれど）
APIのリクエスト・レスポンスに関する破壊的変更の例もあがっていた。（Locations 5221-5289あたり）
名前変更、型変更、必須・任意の変更など。基本的にはその種の変更では破壊的変更になることは避けられないので、初めから一定のオブジェクトに入れておくことで影響を局所化可能な設計にすることが必要そう。
また、こう言った変更を発生させるときにはAPIのバージョニングにより、サポート期間を明示して対応していくことになるけれど、その際の方法について3つ紹介されていたのが興味深かった。
列挙されていたのは次の6つ。
- パス
- ドメイン
- クエリパラメーター
- カスタムヘッダー
- コンテンツネゴシエーション
- コンシューマーの設定（ユーザーとバージョンの紐付け管理）
また、バージョニングについては、API全体でバージョニングするイメージが強いけれど、エンドポイントレベルでのバージョニングも可能ではある旨が紹介されていた。ただし、複数のエンドポイントを組み合わせて使用するとき、どのバージョンの組み合わせが許容されるかなどの理解が難しくなっていくので望ましくはない様子。
次のこれは、安易にBool値を使用するべきでないという戒めの話。
Bool値は一見、取りうる二項値に限定されるのでわかりやすく思える。ただ、実際には、拡張性の観点で難があるので、使用するシーンは選ばないと設計上のリスクになるのだということを改めて理解させられた。
出所：(Kindle Location 5760)
設計ガイドを作る際のレイヤー構成についての説明もわかりやすい。
確かにこういうものを用意しないと、同じチームで継続的にメンテすることが難しくなるかもしれない。
APIの設計ガイドラインは、次の3種類のレイヤで構成できる。
- リファレンスガイドライン：設計の基本的な要素を説明することに焦点を合わせている。
- ユースケースガイドライン：さまざまなユースケースを使って基本的な要素をどのように適用するのかを説明する。
- 設計プロセスガイドライン：APIの設計方法に関するガイダンスを提供する。
(Kindle Locations 8200-8205)
この書籍の最終章には著者がまとめているAPIの設計ガイドラインのページがある。他の有名な会社がどのようにAPIを設計しているかを集めているページに見えたので、レシピサイトまとめのWeb API版といったところだろうか。ただ、こういうものがあると、まさに著者が書いているようにインスピレーションを得やすいので、とても良いと思った。
これまでそれなりに経験のある人にとってもきっと学びのある一冊だろうと思う。
いい具合に咀嚼しつつチームと共有して自分たちのAPIの設計ガイドラインの裏打ちやディスカッションの出発点に使うと良さそう。