SSブログ

API仕様を書く(5)ー gRPC protoファイル ー [API仕様を書く]

(「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の振る舞いを書くのはこの部分が適切かと思います。さらに、以下のことも書き加える必要があります。
  • リクエストの構造体の各フィールドに許される値
  • 許されない値が設定されていた場合に返されるエラー
たとえば、Hellonameフィールドが空を許さないのであれば、空が指定されたらどのようなコードが返されるかと記載する必要があります。

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

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

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

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

続き

コメント(0)