matsuriでいかにして我々が.endpoints.jsonを発明しそれを使っているかについて紹介します。
# はじめに
フロントエンドとバックエンドで API エンドポイントの情報、あるいはそれらのスキーマをどのようにして共有するかという問題はよく知られた問題で、OpenAPI などさまざまなツールが提供されています。matsuri ではこれらを独自に解決する .endpoints.json という仕組みを導入し、またそれらを取り巻く toolchain を自分たちで作ってきた歴史があります。今日はこれらについて少し紹介したいと思います。
# .endpoints.json とは
.endpoints.json は matsuri 内でバックエンドとフロントエンドで API エンドポイントの情報を共有するために定義された matsuri 内の規格です。 OpenAPI などと違う点としては、以下のような点が挙げられます。
- 比較的シンプルであること
- API にバージョニングの概念が組み込まれており、あるバージョン以後では使えないエンドポイントであることなどが表現できること。また SDK のサポートにより、実際にあるバージョン以後はエンドポイントが生成されなくなること
- API セットに名前をつけて、特定の環境向けに生成するしないを切り替えられること。これにより特定のフロントエンドだけが使うことを想定している API エンドポイントの生成などが簡単にできること
- 開発環境と本番環境の URL の切り替えが柔軟にできること
また、思想も異なります。 OpenAPI を使っている環境だと「OpenAPI のスキーマで駆動する」開発を行っているところが多数派に感じており(筆者の感想です)、そのため OpenAPI からのバックエンド・フロントエンドが生成される印象です。 しかし我々の.endpoints.json はそうではなく、あくまでバックエンドが定義した API エンドポイントが、ドキュメントの代わりに生成されるものというような位置付けです。
このような「バックエンドの API で駆動する」開発を行うことが主流の開発スタイルであったので、.endpoints.json を採用(策定？)するに至りました。
# .endpoints.json を取り巻く toolchain
上記に紹介した開発体験を享受するには、2 つのツールが必要です。「バックエンドで書いたコードから.endpoints.json を自動で生成する仕組み」「.endpoints.json からフロントエンド環境向けに SDK を生成する仕組み」 いずれも OSS で提供しています。
↓ Go で書いたコードから json ファイルを生成するツール
↓ .endpoints.json から SDK を生成するツール
弊社ではバックエンドに Rust を採用しているサービスもありますが、こちらについてはプロダクト側のコードに含まれており、OSS としては公開していません。
ちなみにですが、上記の endpoints-go は実は OpenAPI ファイルを生成する機能も付属しています。 こちらは開発に利用するためというよりはドキュメンテーションのためですね。
# .endpoints.json がもたらす開発者体験
.endpoints.json によって、以下のような開発者体験が提供されています。
- バックエンドで API を定義する
- PR を出す
- GitHub Actions により、.endpoints.json が自動生成され commit&push される
- フロントエンド側で.endpoints.json を pull し、SDK を自動生成する
- 生成された SDK のエンドポイントの path や method を利用する
このような流れで、バックエンドとフロントエンドで API エンドポイントの情報を共有することができます。
# スキーマの導入
直近では.endpoints.json にスキーマの機能を導入しました(optional ですが)。 こちらは endpoints-go を使う場合、バックエンドで echo の API 定義メソッドをすり替えるだけで、型から JSON Schema を自動生成し、それを SDK に渡してフロントでインターフェースが生成されるというものです。
(心の叫び) Go 言語でメソッドに type parameter が使えるようになって欲しいな〜これがあるとより開発者体験がよくなるんだけどな〜
# おわりに
.endpoints.json の歴史を振り返りながら、フロントエンドとバックエンドでどのようにして API エンドポイントの情報を共有しているかについて紹介しました。 最近では OpenAPI 派閥や RPC のようなスタイルもある中で、少し異質な開発スタイルを取っているかもしれませんが実際に弊社の開発チームにはなくてはならないツールとなりました。
直近ではスキーマを導入できるようになり、部分的ではありますがフロントでの型定義をする場面を減らせるようになったかなと思います。
まだそこまで使われてはいない機能ですが、この記事を読んだ弊社開発メンバーはぜひ一度触ってみてください。