So-net無料ブログ作成
  • ブログをはじめる
  • ログイン

API仕様を書く(4) [API仕様を書く]

(「API仕様を書く(3)」からの続き)

2017年8月末でリコーを退職して、ソラミツ社で働き始めました。技術的にはgRPCを使ったサーバー側の開発に加わることになりました。

gPRCに触れたのはその時が初めてですが、RPC(Remote Procedure Call)そのものは、Xerox社のCourierとよばれるRPCに1984年から接していましたし、後にSunのRPCを使ったツール開発(MessagingToolと分散コンパイルツール)も行っています。Courierは、XNS(Xerox Network Systems)の各種サーバーのプロトコルを記述するのにも使われており、プロトコル仕様はかなり丁寧に書かれていたと記憶しています。

gRPCは、RPCの定義を.protoファイルに書いてprotocでコンパイルしてスタブを生成します。RPCはその名前が示す通り、Procedure Callであり、Procedureを定義する訳です。呼び出しのパラメータ、呼び出し結果のレスポンスなどをstructとして定義します。また、エラーを通知するためにステータスコードを返すことができるようになっています。ステータスコードは、Javaに例えるとメソッドがスローする例外に相当します。

開発されていたサーバーのgRPCの定義である,protoファイルの中を見ると、何も書かれていませんでした。Javaで例えると、「公開APIのクラスやインタフェースの定義が書かれている.javaファイルに一切Javadocが書かれていない」という状態でした。

『Effective Java 第2版』を読まれたことがあるエンジニアであれば、そのようなクラスやインタフェースは公開APIとしては不適切であることは認識できると思います。『Effective Java 第2版』で該当する項目と章は以下の通りです。
  • 項目44 すべての公開API 要素に対してドキュメントコメントを書く
  • 第9章 例外
もちろん、『Effective Java』はJavaに関する内容なので、.protoファイルでは、そのエッセンスだけを適用して読み替える必要があります。簡単にまとめると、以下のことをAPI仕様として書く必要があります。
  1. 各PRCの説明
  2. 各PRCのリクエストパラメータとレスポンスパラメータの説明
  3. リクエストパラメータの制約(事前条件)とそれに違反したときに返されるステータスコードの説明
  4. RPC呼び出しの制約(事前条件)とそれに違反したときに返されるステータスコードの説明
  5. RPCを実行したときに起きる可能性のあるエラーとそれに対して返されるステータスコードの説明
何も書かれていなかったので、サーバー側のシステムを理解することを目的として、私自身ですべての仕様を.protoファイルの中にコメントとして書きました。仕様を書きながら、不備も多く見つけましたし、gRPCを直接呼び出してテストするコードを書いて、必要あればサーバー側のコードを修正したりもしました。

上記の1.から5.までについては、次回もう少し詳しく書きたいと思います。

(続く予定)



スポンサーリンク





コメント(0) 

コメント 0

コメントを書く

お名前:[必須]
URL:
コメント:
画像認証:
下の画像に表示されている文字を入力してください。

Facebook コメント