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社との共同プロジェクトが中止になって、とても暇になってしまったので書きました。。

（続き）