API仕様を書く（7）

（「API仕様を書く（6）ー gRPC protoファイル（2） ー」からの続き）

きちんとしたAPI仕様を書いていない場合、そのAPIのテストコードは当然のことながら、正常ケースだけだったり、不正なパラメータが渡されたときにどのように振る舞うかは実装のソースコードを見ないと分からなかったりします。さらに、「エラー翻訳」（「例外翻訳」）を行っていない実装は、いつのまにか返されるエラーが変わってしまっていることも起こり得ます。

おそらく多くの大学ではAPI仕様の書き方も含めてAPI設計の教育は行われていないと思います。そして、社会人となってから、個々のソフトウェアエンジニアがAPIの仕様をどの程度記述するかは、その人が属したソフトウェア開発組織の文化に影響を受けると思います。

私自身、gRPCを用いたソフトウェア開発では、前職のソラミツが初めてでした。そこでは、protoファイルには何も仕様が書かれていない理由は、それが大学の学生が作成したものだからだと思っていました。しかし、それは学生が書いたからではなく、そもそもAPI仕様を書くことを行ったことがない人達が書いたものだったからです。つまり、企業でソフトウェア開発をしているソフトウェアエンジニアであっても、仕様を書かない人が圧倒的に多いのではないかということです。

リコーに勤務していた頃は、さまざまなAPIをレビューしましたが、やはりきちんと書いてこないソフトウェアエンジニアが圧倒的に多かったです。その中でも、NDAを結んだサードパーティへ提供するAPIなのに、これはないだろうとう不完全なAPIが多くありました。

不備が多いAPI仕様は、不具合が多いAPI実装を生み出し、そして、サードパーティから問い合わせが多くなり、結果として長期的な開発コストを増加させます。これは、サードパーティへ提供するソフトウェアではなくても、会社内で閉じているソフトウェアでも、長期的な開発コストを増加させる結果となります。

マイケル・C・フェザーズの言葉を置き換えると次のようになるかと思います（「ネーミング」を「API仕様」と読み替えてます）（『レガシーコード改善ガイド』）。

API仕様は設計の中心である。優れたAPI仕様はシステムの理解を助け、作業を容易にする。しかし、貧弱なAPI仕様はシステムの理解を妨げ、後でシステムを扱うプログラマに辛い日々を送らせる。

（おわり）