Good APIs Age Slowly¶
チェック¶
- [ ] 本文を確認した
- [ ] 概要を確認した
- [ ] タグを確認した
- [ ]
inbox/直下へ移行した
概要¶
良いAPIは最初に美しく見えるものではなく、時間が経っても意味が変わりにくいものだという記事。 APIは実装詳細やその日の画面都合を外へ漏らすと、利用者が観測した挙動へ依存し、後から内部変更できなくなる。 バージョニングだけでは悪いAPI設計のコストは消えず、安定した概念と境界を慎重に公開することが信頼を作る。
本文¶
最初のバージョンは評価されすぎる¶
APIの初版は、状況が単純なため良く見えやすい。 作った人は意図を知っていて、利用者も同じ前提で使い、周辺システムもまだ変化していない。
しかし、別チームがバッチ処理から使ったり、暗黙に安定していると思ったフィールドへ依存したり、現在たまたまそう並んでいるレスポンス順へ依存したりすると、内部実装だったはずのものが外部契約になる。 ソフトウェアでは、観測された挙動が意図せず依存対象になる。
API問題の多くは境界問題¶
API設計の主問題は、美しさや名前の良さだけではなく境界にある。 何をpublic contractにし、何を内部実装として閉じるかを早い段階で決めないと、少し便利だからという理由で内部状態や実装都合を外へ出してしまう。
今日の画面に合わせてAPIを作ると、プロダクトイテレーションと同じ速度でAPIが古くなる。 APIは他チームが上に構築するものなので、今日のUIではなく、システムの安定した概念に寄せるべき。
Versioningは救済策ではない¶
バージョニングは重要だが、悪いAPI設計を免罪しない。 APIが実装詳細に結びつきすぎていたり、特定ユースケースに寄りすぎていたりすると、利用者は移行し、再テストし、互換コードを持ち、運用負荷を支払う。
安定したAPIは信頼を作る。 利用者は防御的にならずにその上へ構築でき、驚きの破壊的変更を警戒しなくなる。 APIはドラマではなくインフラになる。
外へ出すものに慎重になる¶
良いAPIは、小さいだけでは足りない。 受け取る入力には少し寛容でもよいが、返すデータや外へ見せる振る舞いには慎重であるべき。
余分な入力を無視することは大きな問題になりにくい。 しかし、余分なデータや振る舞いを返すと、利用者はそれを見て使い、依存する。 外へ出したものは契約になりやすい。
要点¶
- 良いAPIのテストは、初見の美しさではなく、要件や利用者が変わった後も意味が保てるか。
- API設計の失敗は、多くの場合「公開契約」と「内部実装」の境界が曖昧なことから起きる。
- バージョニングは必要だが、実装詳細に依存したAPIのコストを消してはくれない。
- 返すデータや観測可能な振る舞いは、利用者の依存対象になる前提で慎重に選ぶ。