API仕様を書く（2）

（「API仕様を書く（1）」からの続き）

2003年からリコーに転職する2009年まで従事したデジタル複合機のコントローラソフトウェア開発プロジェクト（ピーク時は約100名のソフトウェアエンジニアが従事）では、私が提唱したある方式に基づいて完全なテスト駆動開発を行っていました。そのソフトウェア開発もレイヤ構成のソフトウェアであり、多くはプロセスとして実装され、プロセス間通信をCORBAで行っていました。

今日で言えば、マイクロサービス化してサービス間で通信してシステムを実現しているようなものです。各プロセスは下位層のハードウェアからのイベントと上位層のUIからユーザ指示のイベントの両方を処理する必要があるため、個々のプロセス内ではマルチスレッドプログラミングが行われているというものでした。品質を担保するために、当時としては複写機業界ではトップクラスのテスト駆動開発を行っていました（「マルチスレッドプログラミングにおける重要な４要件」）。

各サービス（プロセス）が提供するAPI仕様は、プロジェクト全体でかなりきちんと書かれていました。このプロジェクトでは、私も中核となる最も複雑な処理を行うサービスを担当して、API仕様を書いて、実装して、テストを書いて、そしてマルチスレッドのデッドロックやrace conditionをひたすらデバッグしていました（さらに付け加えると、開発部門の部長もしていました）。

このプロジェクトでは、API仕様を書く書かないの選択肢は個々のサービス担当者に委ねられることはなく、プロジェクト全体で書くことが強制されてたような気がします（あるいは、ある程度私が強制させていたのかもしれませんが、もうあまり覚えていません）。

振り返ってみると、1984年から2009年までその多くを富士ゼロックスグループで過ごし
、自分自身も多くのAPI仕様を書いてきたので、自分が担当するモジュール、ライブラリ、サービスのAPI仕様を、「利用者の視点を意識して」書いてから実装を行うことが、ソフトウェアエンジニアとして当たり前だと思っていました。そして、一緒に仕事をした多くのソフトウェアエンジニアが同じだったと思います。

2009年8月に富士ゼロックス情報システムを退職して、リコーに転職したのですが、そこは同じ複写機業界でありながら、ソフトウェア開発に関しては全く違う世界がありました。

（続き）

API仕様を書く（1）

株式会社メルペイに入社して、3か月が過ぎました。1984年に社会人となってからさまざまなソフトウェア開発に従事してきましたが、今日でいうところの「Backend Engineer」というのは前職のソラミツ社で少しかじった程度でした。現在は、あるマイクロサービスの開発を担当しており、この3か月間の半分以上は、そのマイクロサービスのAPI仕様を書くことに費やしていました。マイクロサービスの通信は、gRPCで行いますので、API仕様はその.protoファイルにコメントの形式で書いています。

実装をほとんどせずにAPI仕様を書くということをいつ頃からやった経験があるのかと振り返って見ると、1993年から開発に従事したFuji Xerox DocuStation IM 200です。レイヤ構成のアーキテクチャで、最下位層はハードウェアを抽象化したAPIを提供するMCA（Machine Control Architecture）と呼ぶものでした。その層では、IIT（Image Input Terminal：スキャナー）、IOT（Image Output Terminal：プリンター）、Fax、操作パネルといったデバイスに対してハードウェアに依存しない抽象的なAPIを提供するのがMCAの目標でした。その中で、全体の共通仕様とIITとIOTの制御ソフトウェアのAPI仕様を英語で書きました（Xerox社へ提供予定のAPIだったので）。当初、私はAPI仕様だけを書いていたのですが、実装担当者によるAPI仕様の実装が徐々に難しくなっていったため、代わりに私が実装することになって二か月で全部を再実装しました。

その後、MCAの上でコピーサービスとFaxサービスを、私を含めて4人のエンジニアで4週間でプロトタイプして動作させることができたので、そのプロトタイプを捨てて、すべてをきちんと設計することになりました。私は、MCAの上でMAE（Multifunction Application Environment）と呼ぶ層を担当することになり、そのAPI仕様のドラフトを書き上げました。それから実装を始めたのですが、API仕様があるのでテストコードは他の若いエンジニアに書いてもらいながら、彼女と二人でMAEの開発を進めました。

ここまでの経験は、最初にAPI仕様を書いてから、それを実装していくというものです。実装しながら不都合があれば、API仕様はもちろん修正されていきます。

API仕様を書いて、自分では一行も実装を書かない経験をしたのは、現在の富士ゼロックス社のデジタル複合機のコントローラソフトウェアで使われているC++用のライブラリ（こちら）です。2000年のことです。そのライブラリのAPI仕様（日本語）は、本来の動作仕様に加えてかなり防御的に書きました。つまり、不正なパラメータ値を渡した場合の挙動をデバッグ版とリリース版に関して細かく書きました（参考：「API設計の基礎」）。このライブラリの実装は全く行いませんでしたが、実装のコードは全部レビューしました。そして、そのライブラリに関する「Programmer's Guide」（A4で約100ページ）も後に※書いています。
※ Webster, NYに住んでいた2002年の暮れにXerox社との共同プロジェクトが中止になって、とても暇になってしまったので書きました。。

（続き）