実践API設計：柴田芳樹 (Yoshiki Shibata)：SSブログ

	ブログをはじめるログイン

Kindle版『プログラマー”まだまだ”..｜電子版『Go言語100Tips』ブログトップ

実践API設計　[API仕様を書く] [編集]

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

4月に発売された「WEB+DB PRESS Vol.134」で特集1「実践API設計」を執筆していますが、そこから部分的に紹介します（目次は、こちらです）。

第1章「優れたAPI仕様とは何か --- よくある問題と記述すべき事柄」の冒頭で次のように述べています。

　今日、多くの企業がWeb サービスとしてさまざまなサービスを提供しています。Webサービスは、iOS、Android、ブラウザといったフロントエンドと、それらに対して機能を提供するバックエンドサービスから構成されます。バックエンドサービスが提供するさまざまな機能はAPI （Application Programming Interface）として定義され、フロントエンドから呼び出されます。フロントエンドは、バックエンドサービスが提供する機能を使ってユーザーへ提供する機能を実現します。
　定義されたAPI を介することで、フロントエンドとバックエンドサービスが、独立して、異なるプログラミング言語で開発できます。その結果、バックエンドサービスの開発チームは、定義されたAPI どおりにバックエンドサービスが正しく動作することを保証する責任を負います。つまり、API 定義に従って正しく動作することを、フロントエンドを接続することなく、自動テストで確認することが求められます。
　Web サービス開発の中で意外と難しいのが、バックエンドサービスのAPI を設計し、そのAPI 仕様を記述し、そしてテストファーストによるテスト駆動開発を行うことです。この特集では、それらが何を意味し、開発者にとって日々の活動で何をしなければならないかを解説します。

（太字で青にしている部分は、このブログで強調するためのものです）

長年、デジタル複合機を中心とした組込システムの開発に従事してきましたが、リコーを退職した後、2017年9月から、ウェブサービス（バックエンド）の開発に従事してきました。

当初から驚いたのが、バックエンドのサービスのAPIは定義するが、そのAPIで定義したエンドポイントを直接呼び出してサービスの機能を確認テストを書くことがほとんどないことです。つまり、さまざまなモジュールの単体テストはあるのですが、すべてを結合して一つの実行バイナリにして、APIで定義されたエンドポイントを外部から呼び出すテストコードがないことです。

この6年間で見られた問題点の多くは、「API仕様でよくある問題点」で次のように述べています。

　筆者はこれまで、Web サービス開発だけでなく、組込みシステムを含むさまざまなソフトウェア開発に従事してきました。それらの開発を通してAPI 仕様のさまざまな問題を目にしてきましたが、主なものとしては次の3つが挙げられます。

API仕様が書かれていない

エラーの記述がない

自動テストが存在しない

　この結果、開発現場でよく起こるのは次のようなことです。

正確な仕様は、実装コードを読まないとわからない

どのような場合にどのようなエラーが返ってくるかは、実装コードを読まないとわからない

自動テストがないため、API がどのように振る舞うのかを簡単に知る方法がない

　これらの3つの問題をもう少し詳しく見ていきます。

記事では、これらの問題点をさらに詳しく説明しています。

ここでの問題点は、この6年間で働いてきたソラミツ、メルペイ、カウシェの3社で入社した当初に、私が目にしたバックエンドのサービス開発のほぼすべて（ただし、メルペイで私が最初に担当したマイクロサービスを除く）で目にしてきたものです。

その都度、この特集記事で述べたことを実践して改善していきました。改善は、単に私一人が行うものではなく、同じチームのメンバーが上記の問題を起こさないように開発を行ってくれるように、意識も行動も変わってくるようにするというものです。結果として、上記の問題を残さないようにする開発組織へと変わっています。

3社での経験から、おそらく多くの企業でこの問題は見られるのではないかと思っています。

関連記事：「伸ばすのが難しい能力」

（2023年8月15日追記：下記は、『WEB+DB PRESS, Vol.134』のp.12より引用）