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版

株式会社令和トラベルで働きます

一か月前に「株式会社カウシェを退職します」を書きました。その時点で12月からの勤務先は決まっていませんでしたが、12月1日より株式会社令和トラベルで、嘱託社員契約でバックエンドエンジニアとして働きます。

勤務形態

週4日（月曜日〜木曜日）勤務です。週4日勤務は、2017年9月から続けている勤務形態です。

オフィスは渋谷（カウシェの新たなオフィスの近く）ですが、基本的に自宅からフルリモートで働きます。実は、1年2か月在籍したカウシェには、入社前にオフィスへ行ったことはあるのですが、在籍期間中は一度も出社しませんでした。

9社目

11月で64歳になり、令和トラベルで社会人になって9社目となります。

• 富士ゼロックス（1984年4月入社）
• 日本オラクル
• ジャストシステム
• 富士ゼロックス情報システム
• リコー
• ソラミツ
• メルペイ
• カウシェ

私の世代は定年まで1つの会社で働き続けるのが普通でした。実際、富士ゼロックスでの同期や後輩の多くは60歳の定年まで勤めています。私自身は、「定年退職」を経験したことはなく、どの会社も定年退職前に退職したことになります。

バックエンド開発

ウェブサービスのバックエンドとしてのキャリアはソラミツからなので、すでに6年を超えたことになります。ただ、今まではGo言語での開発でしたが、令和トラベルではTypeScriptなので、一から学習しながらということになります。

これまでのバックエンドの開発経験を活かし、私にとっては初めての旅行という領域でサービスを開発しながら、これから大きくなっていく開発組織をいかにスケールアップできる組織にしていくのかという点についても貢献できればと思っています。