Web APIの設計
APIはアプリケーションのインターフェース。UIみたいなもの。自分以外の誰かが使う。APIの設計がクソだとUIがクソなアプリが使いにくいように他人に負担を強いることになる。さらにAPIの変更はユーザに新たな学習を強いるので難しいことが多い。APIに"設計"が必要な理由はここにある。
プロバイダ視点でAPIを作ると無駄に冗長になって使いにくくなる。ユーザーのニーズを把握しそれに合わせて抽象化して提供することが重要。APIゴールキャンバスに沿って設計すると良い。 APIゴールキャンバスとはhttps://scrapbox.io/files/66e796252705f1001c01e378.png
誰が : API のユーザーをリストアップ
何を : ユーザーができることをリストアップ
どのように : 「何を」 を複数ステップに分解
入力 (および、その入手元)
出力 (および、その用途)
ゴール : どのように + 入力 + 出力 をわかりやすく言い換える
RESTアーキテクチャスタイル
設計前にいきなりOpenAPIを書き始めない。あくまで設計されたAPIをプログラマブルな文書として起こすために使う。
OAS(OpenAPI Specification) + JSON SchemaでAPI仕様をプログラマブルな仕様として記述できる
第２部は命名規則やHTTP標準の機能を使えとか一貫性がどうのこうのと色々実例を挙げて書かれているが、結局はユーザビリティを考慮したAPIにしろ異常のエッセンスはない
第３部は雑多なAPI設計関連まとめ
セキュリティ: 認可の制限、アクセスできるAPIの制御(スコープ設計)、APIで提供するデータの制限など当たり前のことが多い
小さく作れば拡張に強くなる→コンテキストを分割してAPIを設計
ドキュメント重要。OAS。
SSEでstreaming形式のAPI
ドキュメント重要。それはそう。
結局一貫してユーザビリティを高めるという点を全ての判断軸に据えて、そのためにインターフェースや命名規則を決めたりドキュメント化したりする。意識することはそれだけっぽい。API設計という抽象的な話をメインに書かれている本なので実装について触れられておらず、具体的にどうそれらの原則を落とし込むのかというのはケースバイケースということなのだろうな。
まぁなんというか1,2,3章が全ての要点であるのでそこだけ読む、プラスでOpenAPIの話とかちょこっと読めば十分かも。あとは実務の中で実際にAPIを実装していく中で壁にぶつかりながらちょっとこの本のことを思い出すみたいな感じの使い方が良さそう。