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_です

Martin FowlerのREST APIの設計レベル

REST API LEVEL 3のHATEOASの概念導入については知らなかった考え方なので勉強になりました。

SSKDsをターゲットとしたAPIを作ることが多いので、今後HATEOASな設計にもチャレンジできるように理解を深めていきたいと思います。

おわりに

仕事ではフロントエンドの開発を中心にやっているのですが、API設計も原則はフロントエンドの設計原則と同じように感じました。保守性が高くなる設計をするために、分かりやすい名称にする、無駄を排除する、抽象化して内部構造が上位レイヤーに漏れ出さない様に疎結合化する。

このような原則を常に意識しながら今後の開発に活かしていこう、というのを改めて認識させてくれました。