[章番号]: [サービス名] gRPC API仕様書

このテンプレートの使い方

このファイルは、gRPC APIの仕様を定義するためのテンプレートです。 gRPCの仕様はProtocol Buffers (.proto) ファイルが中心となるため、このドキュメントは.protoファイルへの参照と、各RPCメソッドの目的や使用例を補足説明することに重点を置きます。 詳しい使い方は「設計仕様の書き方ガイド」を参照してください。

1. はじめに

1.1. 目的

1.2. 対象読者

2. 基本情報

項目	内容
パッケージ名	[例: user.v1]
サービスアドレス (Staging)	grpc://staging.api.example.com:50051
認証方式	[例: mTLS (相互TLS認証)] (詳細はAPI設計共通ガイドラインを参照)

3. Protocol Buffers定義 (.proto)

サービスとメッセージの完全な定義は、以下の.protoファイルを参照してください。

• user_service.proto

---

4. サービス詳細: [サービス名]

4.1. [RPCメソッド名]

• 概要:

IDを指定して、単一のユーザー情報を取得します。

• .proto定義:

  // ユーザー情報を取得するRPC
  rpc GetUser (GetUserRequest) returns (User);
  

• リクエストメッセージ: GetUserRequest

  message GetUserRequest {
    // 取得したいユーザーの一意なID
    string user_id = 1;
  }
  

• レスポンスメッセージ: User

  message User {
    string user_id = 1;
    string name = 2;
    string email = 3;
  }
  

• ストリーミング: なし (Unary)

---

4.2. [別のRPCメソッド名] (ストリーミングの例)

• 概要:

指定された条件に一致するユーザーのストリームを取得します。

• .proto定義:

  // ユーザーをストリーミングで検索するRPC
  rpc ListUsers (ListUsersRequest) returns (stream User);
  

• リクエストメッセージ: ListUsersRequest

  message ListUsersRequest {
    // 検索フィルター (例)
    string role_filter = 1;
  }
  

• レスポンスメッセージ: stream User

• ストリーミング: サーバーサイドストリーミング

---

5. エラーハンドリング

gRPCの標準ステータスコードを利用してエラーを通知します。詳細はレスポンスのmetadataに含まれる場合があります。

ステータスコード	gRPC定義	説明
5	NOT_FOUND	指定されたリソースが見つからない。
3	INVALID_ARGUMENT	リクエストの引数が不正（バリデーションエラーなど）。
16	UNAUTHENTICATED	認証情報がない、または無効。
7	PERMISSION_DENIED	認証は成功したが、リソースへのアクセス権がない。
13	INTERNAL	サーバー内部で予期せぬエラーが発生した。