WEB API :The Good Partsを2章まで読んだ

はじめに

仕事でWEB APIを設計する機会があったのですが、「良いAPI設計とは何だろう？」という疑問がそもそもありました。同僚から本書を紹介してもらったので読んでみました。

Web API: The Good Parts

作者:水野貴明
オライリージャパン

Amazon

理解・感想

良いURI設計をするにあたるメモ

設計するにあたる考え方の背景
- SQLのようにテーブルアクセスするのをただ内包しただけでは、ユーザが内部のテーブル仕様を知ってないといけない。
- 内部構造を公開するとセキュリティが怪うくなる
  - したがってもう少し高い次元で機能を設計する必要がある
公開したAPIがどのように使用されるかユースケースをきちんと考えること
- LSUDsなのか、SSKDsなのか
覚えやすく、どんな機能を持つURIなのかが一目でわかるようにすること
- 短く入力しやすい
  - やたらに”api”という文字を繰り返し含まない、とか。
- 人間が読んで理解できる
  - 名称はわかりやすい単語で
    - どうしたらいいか分からない場合は、ProgrammableWebを参考にする
    - 余談：httpヘッダはreferrerが正しいのにrefererとなってしまってる。
- 大文字小文字が混在していない
  - 小文字で統一する
  - キャメルケースも良くない
  - HTTPの世界ではURIはホストとスキーマ以外は大文字小文字が区別される仕様
- 改造しやすい
  - HATEOASというRESTを拡張した概念においては、Hackableでない方が良い、という考え方もある
- サーバ側のアーキテクチャが反映されていないこと
  - Table APIとかはテーブル指定でデータ取得できちゃうからセキュリティ的にも良くないし、ユーザはテーブル構造知らなきゃいけないので良くなさそう
- URIの付与ルールが統一されていること

認可フローについて

元々grant Typeが複数あり、Authorization code flowとかは使ったこともあり知っていましたが、その他のフローの違いが良く分かってなかったです。本書を読むことで再度調べるきっかけとなり、解像度高く理解することが出来ました。以下のサイトが参考になりました。

https://qiita.com/TakahikoKawasaki/items/200951e5b5929f840a1f

オーケストレーション層という考え方

私はTypescript / Next.jsでの開発を行うことが多いです。そして、Next.jsはサーバサイドにてapi routeにてapiを構築することが出来るのですが、これについて「backendでAPIを作るのにわざわざapi routeでラップする必要があるのか？」といった場面に遭遇しました。backendサーバをクライアントから隠蔽する、というが目的の一つとしてはあるのですが、オーケストレーション層として使う、という考えがしっくりきました。 https://parkpark.dev/posts/nextjs-api-to-bff

また、「あれそういえばBFFとの違いって何だっけ？」というのも調べるきっかけとなり、BFFはフロントエンドのためのオーケストレーション層である、ということも理解しました。

https://scrapbox.io/terfno/BFF∈Orchestration_Layer_です