API仕様を書く（5）ー gRPC protoファイル ー

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

RPCの実装も通常のライブラリを作成するように「防御的プログラミング」を必要とします。すなわち、以下の状態に正しく対処する必要があります

• パラメータ値不正
• 呼び出し順序不正
• 設計ロジックの誤り

最初の二つは呼び出した側の誤りのですので、そのような不正呼び出しに対して、どのようなエラーを返すかを記述する必要があります。三つ目は設計ロジックの誤りです（これらの三つの詳細な説明については、『API設計の基礎』の「第3章 防御的プログラミング」を参照してください）。

gRPCのprotoファイルの例として、https://grpc.io/docs/guides/ には次のようなサンプルが掲載されています。

// The greeter service definition. ①
service Greeter {
  // Sends a greeting　②
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.　③
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings　④
message HelloReply {
  string message = 1;
}

番号（①、②、③、④）は私が説明用につけたものです。

①には、定義するサービスの説明を書く必要があります。この例では、RPCが一つしかないですが、通常は複数のRPC定義が書かれますので、サービスが提供する機能の概要を書く必要があります。サービスによっては、数行ではなく、10行以上の説明になることもあるかと思います。

②には、簡単にRPCの説明が書いてあれば十分かと思います。なぜなら、RPCの細かな振る舞いやリクエスパラメータにおける事前条件を説明しようとすると、パラメータである構造体やレスポンスである構造体のフィールドが同じ箇所に書かれていないので、②に書くには不適切かと思います。実際、私が仕事で書いているマイクロサービスにはRPCの定義が30個以上あります。

③は、RPCに対応したリクエストパラメータの構造体定義ですので、そのRPCの振る舞いを書くのはこの部分が適切かと思います。さらに、以下のことも書き加える必要があります。

• リクエストの構造体の各フィールドに許される値
• 許されない値が設定されていた場合に返されるエラー

たとえば、Helloのnameフィールドが空を許さないのであれば、空が指定されたらどのようなコードが返されるかと記載する必要があります。

不正なパラメータの場合、単純にリクエストのフィールドの値が仕様で要求される形式や値を満たさないのであれば、InvalidArgumentでよいかと思います。そうではなくて、たとえば指定されたデータがデータベースに無いのであれば、NotFoundかもしれません。

gRPCには成功のOKを含めて標準のコードが17個定義されています（Go言語用の定義はこちら）。どのような場合に、どのようなエラーコードを返すかは、きちんと設計し、かつ、API仕様に明確に記述しなければなりません。つまり、③の部分に明確に記述する必要があるということです。

上記の例では、実際には何も書かれていません。nameが空でもよいのか、空を許すとしたらそれは何を意味することになるのか、空を許さないとしたら空の場合どのエラーコードが返されるのか、呼び出すのに認証は必要ないのかとかです。

④のレスポンスについては、理解するために必要な説明を書く必要があります。自明の場合には、何も書かなくてもよいかもしれません。

（続き）