tobb422のブログ

スタートアップエンジニアの奔走

SPAで利用するAPI設計を考える...

はじめに

ここ 1, 2年は、SPA + API という構成 Web アプリケーションを開発することが多く、
その度に、毎回悩み・後悔しているのですが...
書籍や Web 上に公開されている記事を読んだり、チームで API を設計・開発していく中で
少しずつではありますが、考え方がまとまってきたので、
未来の自分のためにも一度整理しておきます。
※ こちらのメモでは、チームで API を開発することを想定しています。

先人に学ぶ

Web API: The Good Parts では、
設計の美しい WebAPI について以下のような要素を挙げていました。

  • 使いやすい
  • 変更しやすい
  • 頑強である
  • 恥ずかしくない

また、APIデザインの極意 Java/NetBeansアーキテクト探究ノート では、
APIの品質検査方法として、以下を挙げています。
[補足]
こちらの書籍は、公開APIを前提にしているケース(LSUDs)が多く、
今回議題にあげているような、クローズドな Web API (SSKDs)を想定しているわけではないのですが、
いずれにせよ、参考にできることは非常に多いと、私は考えています。

  • 理解しやすさ
  • 一貫性
  • 発見できること
  • 局所性

(※ 詳しくは、書籍をご覧ください。)

上記の項目や、他の Web上で公開されている記事, チーム開発を通して、
現在、私の中では一貫性のある API がホットワードになっています。
一貫性が存在することで、特に理解しやすさ, 使いやすさは向上するのではないか
と考えおり、チーム開発において、ハッピーになれる人が増えると思っています。

一貫性があるAPIを開発するために...

一貫性を確保することは、非常に難易度が高いです、、
そして、チームの人数(関係者)が増えれば増えるほど、運用が難しいように思えます。
チーム開発をしていく中で、一貫性がある API を開発するために心がけていることをメモしておきます。

  • なるべく Web の標準に従う
  • クライアントを意識したリソースを定義する
  • ドキュメントを書く(利用者向け & 開発者向け)

詳しく追っていきます。

なるべく Web の標準に従う

結論からいうと、Web 標準というよりも、REST に従うことを意識するのが良いかなと思っています。

  • URL で、スコープ(どんなリソースか)を定義し
  • HTTP メソッドで、アクション(何をするか)を定義し
  • 統一された リソース を返す

上記に従う形で、設計をするのが良いのではないかと考えています。

クライアントを意識したリソースを定義する

上記の RESTful な API 設計にも重なる項目なのですが、
「統一されたリソース」は、必ずしも、バックエンドが知っている「モデル(= エンティティ)」と同じではないと考えています。
ここが、SPA で利用する API 設計らしさかなと思うのですが、(よく BFF として語られているようにも思います。)
今回想定しているような API 設計では、SPA を意識したもので良くて、
SPA で扱いやすい単位に、各エンティティを集約することが重要な気がします。
「1つのリソース = 1つのモデル」ではない
ということです。
私は、この集約する層をドメイン駆動設計にちなんで、Repository 層と呼ぶことが多いです。

f:id:tobb422:20190514092034p:plain
Repository層

あらゆるエンティティをもう少し SPA で利用しやすい単位にまとめて返すことが良いと考えています。
ただし、各ページに依存してしまうのは良くないので、難しいところです。
リソースを定義するために、
フロントエンドチームと議論しながら、そのアプリケーションで扱うドメインの定義を行っていく必要があると思います。

ドキュメントを書く(利用者向け & 開発者向け)

利用者向けのドキュメントでは、
主に、公開しているエンドポイント、そして定義されているリソース
を書いていくようにしています。
最近、Nest.js という FW を使って、個人アプリを作ることが多いのですが、
その場合は、Swagger のライブラリを導入することで自動でドキュメントを出力してくれます。
色んな FW で同じような仕組みを取り入れていると思うので、そちらを利用するのが便利だと思います。

開発者向けのドキュメントでは、
命名規則や、アンチパターンなどをまとめておくようにしています。
リソースの定義も書いておくと良いかもしれません。
一貫性を確保には、メンバー間での調整がかなり必要で
調整をなくすためにも、明文化できるものは全て記載しておくくらいでも良いかなと思っています。
また、こちらはドキュメントというよりも設計全般の話ですが、
開発者は、全てを知らなくても良いコーディング方法を見つけられる(選択的無知)
を意識して置くことも必須です。

まとめ

SPA で利用する API 設計の勘所として、一貫性がある API をテーマにしました。
そして、一貫性がある API を運用する要素として、以下の要素挙げました。

  • なるべく Web 標準に従う(RESTful な API
  • クライアントを意識したリソースを定義する
  • ドキュメントを書く(利用者向け & 開発者向け)

もちろん、これが正解というわけではなく、1つの考え方として思ってもらえると幸いです。

参考にした書籍・Webページ

[書籍]
Webを支える技術 -HTTP、URI、HTML、そしてREST (WEB+DB PRESS plus)
Web API: The Good Parts
APIデザインの極意 Java/NetBeansアーキテクト探究ノート
エリック・エヴァンスのドメイン駆動設計

[Webページ]
翻訳: WebAPI 設計のベストプラクティス
ぎんざRuby会議01にて、「マイクロサービス指向 Rails API 開発ガイド」という発表をしました