アプリケーションを構築する際にフロントエンドとAPIを分担して開発することはよくあると思います。
筆者もサーバーサイドエンジニアとしてAPIを開発し、モバイルエンジニアにはモバイルアプリの開発をしてもらっています。
この開発スタイルでAPIを構築する際には我々はAPIの仕様書を先に作成して、インターフェースについての合意を先に取ってから各自が開発を進めている。
一方でコードを先に書くスタイルもある。
それぞれの差を理解し、どちらが適しているかを考えてみたい。
スキーマファースト/APIファースト
スキーマファースト/APIファーストとは、APIの仕様を先に決めてから開発を進めるスタイルです。
最初に書きましたが、APIの仕様書を先に作成して、インターフェースを確定してからそれぞれの開発を進めるスタイルです。
このスタイルのメリットは
- 仕様が明確になる
- フロントエンドとバックエンドの開発を分業しやすい
といった点があります。
APIの仕様を先に決めてから開発を進めるためドキュメントが強制的に残るため、一定規模以上の開発の進捗がスムーズになるかなと思います。
一方でデメリットとしては
- ドキュメントの作成に学習時間と作業時間がかかるため、小規模な開発ではオーバーヘッドが大きくなる
- ドキュメントとコードの整合性を保つための手間がかかる
などがあります。
コードファースト
一方でコードファーストとは、コードを先に書いてからAPIの仕様を決めるスタイルです。
つまり実装ありきで開発を進め、ドキュメントが後から生成されるようになります。
このスタイルのメリットは
- 早く開発を開始できる
- ドキュメントを自動生成すればスキーマを書く手間が省ける
といった点があります。
例えばFastAPIを使うと、コードを書くだけでSwagger UIを生成することができ、スキーマを書く手間が省けます。
一方でデメリットとしては
- 仕様が不明確になる
- フロントエンドとバックエンドの開発が分業しにくい
などがあります。
どちらが適しているか
これは状況によるが、筆者はスキーマファーストを推していきたい。
スキーマを先に定義することでクライアントとサーバーのインターフェースを明確にし、開発をそれぞれで行うことができることを享受したいからである。
またOpenAPIで定義されたスキーマは各言語に対応したコードを自動生成するツールがあるため、設定を行って自動生成をすることで一部のコードを書く手間も省ける。
人間がコードを書くことで生じるミスを減らすために自動生成に頼りながらスキーマファーストを用いてチームでの開発効率推していきたい。