API仕様ファースト開発

「API仕様ファースト開発」という用語は、私自身が雑誌「WEB+DB PRESS Vol.134」の特集1「実践API設計」を執筆する際に考えた造語です。

全く新規にサービスを開発する場合の開発順序は次のようになります（記事の題3章の図1）。

図1 API仕様ファースト開発での開発順序

これは、私自身が初めてメルペイで担当して、一からマイクロサービスを開発したときの開発順序です。そして、その後、チーム移動により別のマイクロサービスの開発へ移動したり、カウシェへ転職したりした際に、最初に導入したのはE2Eテストフレームワーク（記事の第4章「E2Eテストフレームワークの構築」）でした。

そして、API仕様の技術的負債（エンドポイントの仕様が書かれていなくて、それをテストするE2Eテストもない状態）を返済するために、次の開発順序（記事の第5章の図1）を自分自身も行い、他の開発者達にも行ってもらうようになりました。

図1 既存のエンドポイントの修正順序

新たなエンドポイントの追加の場合は、次の開発順序（記事の第5章の図2）となります。

図2 新たなエンドポイントの追加順序

この開発プロセスが定着すると、バックエンドサービスの既存のエンドポイントの修正や新規のエンドポイントの追加の際に、最初に行われるのは次のようになります。

1. 仕様の修正のPR（Pull Request）の作成（新規の場合、新規の仕様のPR）
2. 主にフロントエンド開発者による仕様PRのレビューとフィードバック（そして、承認）
3. バックエンド開発（E2Eテスト修正・作成およ実装）
4. バックエンド開発者によるテストコードと実装のPRのレビュー、フィードバック、承認

この開発プロセスが定着すると、次のようなことが利点として発生します。

• フロントエンド開発者は、バックエンドのAPI仕様がきちんと記述されていることを期待し、不明点や不足点は仕様に反映される。つまり、ミーティングで口頭で聞いたり、Slackで問い合わせただけの状態にならないようになります。
• バックエンド開発者も、たとえ自分で過去に担当して開発してエンドポイントであっても、その詳細を忘れることはよく発生します。その場合、実装を読み直すことなく、API仕様を確認できる。結果として、問い合わせがあった時に、実装を読み直す必要がなくなります。
• 新たにチームに加わったしたフロントエンドおよびバックエンドの開発者は、個々のエンドポイントの仕様を、他のバックエンド開発者に問い合わせることなく理解できます。

さらに、このような開発手順が定着して日々行われている開発組織に、同じ経験がない開発者が新たに加わった場合でも、次のようになるはずです。

• API仕様を記述しないで仕様のPRを出しても却下される。たとえば、gRPCであれば、.protoファイルにメッセージ定義しかなく、何も説明が書かれていなかったり、記述されていなかったりする。GraphQLでは、Mutationの新たなエンドポイントのtype定義はあるが、何も仕様が記述されていないとか。
• 実装のPRに、エンドポイントの仕様に基づくE2Eテストが書かれていない場合、却下される。

結果として、API仕様ファースト開発経験がない開発者が開発組織に加わっても、かなり早い段階で、API仕様ファースト開発を行うようになり、API仕様の技術的負債を積み上げることはなくなります。つまり、開発者の増加に対して、スケールアップする組織となっていきます。

逆の状況では、API仕様の記述がなく、API仕様に基づくE2Eテストがないまま開発していると、API仕様の技術的負債を積み上げていくだけです。そして、新たな開発者が加わっても、API仕様ファースト開発経験がない開発者なら、技術的負債を返済することなく積み上げるだけとなってしまいます。

WEB+DB PRESS Vol.134

• 出版社/メーカー: 技術評論社
• 発売日: 2023/04/22
• メディア: Kindle版