API を設計する

前章で .proto の書き方を覚えました。文法が分かれば API は書けます。 しかし「書ける」と「設計できる」は別のことです。

API は一度公開すると、もう自分の都合では変えられません。 この章では、後から直せなくなる前に決めておくべきことを扱います。

API を変えられないのはなぜか

自分のサービスの中の関数なら、名前が気に入らなければ今すぐ変えられます。 IDE のリネームを実行して、テストを通して、デプロイして終わりです。

API は違います。

   あなたのサービス（v1 を公開）
        ▲    ▲    ▲
        │    │    │
     注文    通知   管理画面     ← 3つの別チームが既に呼んでいる

フィールドを1つ消すと、次のことが起きます。

あなたの1行の修正が、他チームの1週間になります。 だから API の設計は、実装を始める前に時間をかける価値があります。

呼ぶ側の都合で設計する

新人が最初にやってしまう設計は、自分の DB のテーブルをそのまま外に出すことです。

// 悪い例: 内部のテーブル構造がそのまま出ている
service UserService {
  rpc SelectUserRow(SelectUserRowRequest) returns (UserRow);
  rpc SelectUserProfileRow(SelectUserProfileRowRequest) returns (UserProfileRow);
  rpc SelectUserSettingRow(SelectUserSettingRowRequest) returns (UserSettingRow);
}

これは動きます。実装も楽です。しかし次の問題があります。

• 呼ぶ側はあなたのテーブル設計を知らないと使えません
• ユーザー1人を表示するのに3回呼ぶ必要があります
• テーブルを3つに分けるのをやめた瞬間、API が壊れます

// 良い例: 呼ぶ側が欲しい単位で切る
service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
}
 
message GetUserRequest {
  string user_id = 1;
}
 
message GetUserResponse {
  User user = 1;
}

テーブルが3つでも5つでも、呼ぶ側には関係ありません。 API の形は、データの保存方法ではなく、使われ方から決めます。

設計を始める時の最初の問いは1つです。

この API を最初に呼ぶのは誰で、その人は何をしたいのか。

答えられないなら、まだ設計を始めるには早いです。

RPC の粒度

粒度は、設計で最も判断を迫られる論点です。細かすぎても粗すぎても失敗します。

細かすぎる — N+1 の API 版

「ユーザー一覧を表示し、それぞれのフォロワー数を出す」画面を考えます。

// 悪い例: 細かすぎる
rpc ListUserIds(ListUserIdsRequest) returns (ListUserIdsResponse);
rpc GetUserName(GetUserNameRequest) returns (GetUserNameResponse);
rpc GetFollowerCount(GetFollowerCountRequest) returns (GetFollowerCountResponse);

50人表示するには 1 + 50 + 50 = 101回の呼び出しが必要です。 データベース章で出てくる N+1 問題と、まったく同じ構造がネットワーク越しに起きます。 しかも1回あたりのネットワーク往復は、DB クエリよりずっと高くつきます。

// 良い例: まとめて取れる
rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
 
message ListUsersResponse {
  repeated UserSummary users = 1;   // 名前もフォロワー数も入っている
  string next_page_token = 2;
}

粗すぎる — 使わないデータまで返る

逆に、何でも返す巨大な RPC も失敗します。

// 悪い例: 粗すぎる
message GetUserResponse {
  User user = 1;
  repeated Post all_posts = 2;         // 1万件あるかもしれない
  repeated User all_followers = 3;     // 10万件あるかもしれない
  PaymentHistory payment_history = 4;  // 名前を出したいだけの画面にも渡る
}

• 名前だけ欲しい画面でも、全部の計算が走ります
• 支払い履歴が要らない呼び出し側にも個人情報が渡ります
• 遅い部分（フォロワー全件）が、速い部分の足を引っ張ります

判断の基準

画面やユースケースを1つ思い浮かべて、それが何回の呼び出しで完成するかを数えてください。 1〜2回で終わるのが理想です。

命名 — 一貫性が最優先

次の API を見てください。

// 悪い例: 動詞がバラバラ
service UserService {
  rpc FetchUser(FetchUserRequest) returns (User);
  rpc GetUserList(GetUserListRequest) returns (UserListResponse);
  rpc UserCreate(UserCreateRequest) returns (UserCreateResponse);
  rpc ModifyUser(ModifyUserRequest) returns (User);
  rpc RemoveUserById(RemoveUserByIdRequest) returns (RemoveUserByIdResponse);
}

個々の名前は、それ単体では間違っていません。問題は混ざっていることです。 使う側は毎回エディタの補完を眺めて「取得は Fetch だったか Get だったか」を確認することになります。

// 良い例: 5つの標準動詞に揃える
service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
  rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse);
}

5つに収まらない操作

現実には「注文をキャンセルする」「記事を公開する」のような操作があります。 これを無理に Update に押し込めると、意図が消えます。

// 悪い例: 何をしているのか読めない
rpc UpdateOrder(UpdateOrderRequest) returns (UpdateOrderResponse);
// 呼ぶ側: status を "CANCELED" に変える…でいいんだよね？
 
// 良い例: 操作を名前にする
rpc CancelOrder(CancelOrderRequest) returns (CancelOrderResponse);
rpc PublishArticle(PublishArticleRequest) returns (PublishArticleResponse);

専用の RPC にすると、次が設計できるようになります。

• 権限 — キャンセルだけ別の権限にできる
• バリデーション — 「発送済みはキャンセル不可」をサーバー側で保証できる
• 監査ログ — 誰がいつキャンセルしたかを残せる
• エラー — 「既にキャンセル済み」を明確に返せる

Update で status を書き換えさせると、この4つすべてが呼ぶ側任せになります。

リクエストとレスポンスは必ず専用メッセージにする

一見冗長に見えるルールですが、これは将来の変更余地を買うためのものです。

// 悪い例: 引数を直接渡し、ドメイン型を直接返す
rpc GetUser(google.protobuf.StringValue) returns (User);

半年後、次の要望が来ます。

• 「取得時に、自分がフォローしているかも一緒に返してほしい」
• 「言語を指定して、その言語の表示名を返してほしい」

引数が StringValue ではフィールドを足す場所がありません。 User を直接返していると、is_following を User に足すことになりますが、 これは「ユーザーそのものの属性」ではないので、他の RPC でも意味不明な値が付いて回ります。

// 良い例: 専用の Request / Response を挟む
message GetUserRequest {
  string user_id = 1;
  string language_code = 2;   // 後から足せる
}
 
message GetUserResponse {
  User user = 1;
  bool is_following = 2;      // 「この呼び出しの文脈」の情報はここに置く
}

ルールは単純です。

• すべての RPC に XxxRequest / XxxResponse を作る
• フィールドが1つでも、空でも作る
• ドメインのメッセージ（User）はレスポンスの中に入れる。直接返さない

空の Response も同じ理由で作ります。google.protobuf.Empty を返すと、 後から「削除件数を返したい」と思っても足せません。

ページネーション

一覧を返す RPC には、必ずページネーションを入れます。 「今はデータが100件だから全部返す」という API は、データが増えた日に落ちます。

offset 方式の問題

// 悪い例
message ListUsersRequest {
  int32 offset = 1;
  int32 limit = 2;
}

SQL の LIMIT 20 OFFSET 40 にそのまま対応するので、実装は簡単です。 問題は2つあります。

1. 途中で挿入・削除されるとズレます。

時刻 T1: 1ページ目を取得（offset=0, limit=3）
   [A, B, C]  ← 取得できた

時刻 T2: 誰かが新しいユーザー X を先頭に追加
   [X, A, B, C, D, E]

時刻 T3: 2ページ目を取得（offset=3, limit=3）
   [C, D, E]  ← C が2回出てくる。取りこぼしも同じ理屈で起きる

2. 深いページが遅くなります。

OFFSET 100000 は「10万件読んで捨てる」という意味です。 INDEX が効いていても、捨てる分の走査は発生します。 ページが深くなるほど線形に遅くなり、ある日タイムアウトします。

cursor 方式

// 良い例
message ListUsersRequest {
  int32 page_size = 1;      // 1ページの件数（上限はサーバーが決める）
  string page_token = 2;    // 前回のレスポンスの next_page_token をそのまま渡す
  string order_by = 3;      // "create_time desc"
  string filter = 4;        // "status = ACTIVE"
}
 
message ListUsersResponse {
  repeated User users = 1;
  string next_page_token = 2;   // 空文字なら、これが最後のページ
}

サーバー側は「前回の最後の要素の位置」をトークンに詰めて返し、 次回は WHERE (create_time, id) < (前回の値) のように続きから読みます。 何件目かではなく、どこまで読んだかを持ち歩くので、挿入されてもズレず、深いページも遅くなりません。

「5ページ目に飛べない」は本当の制約です。 管理画面のようにページ番号での移動が要件なら offset 方式を選ぶ、 無限スクロールや同期処理なら cursor 方式、という判断になります。 判断の理由を .proto のコメントに1行書いておいてください。

部分更新 — 全体更新は他人の変更を消す

更新 API で最もよくある事故がこれです。

// 悪い例: User をまるごと受け取って上書きする
rpc UpdateUser(User) returns (User);

呼ぶ側は「読んで、直して、書く」をします。

10:00:00  画面A が GetUser →  { name: "佐藤", email: "a@example.com" }
10:00:05  画面B が GetUser →  { name: "佐藤", email: "a@example.com" }
10:00:10  画面B が email を変更して UpdateUser → email が "b@example.com" になる
10:00:30  画面A が name だけ変更して UpdateUser
          → 手元の古い email "a@example.com" ごと送るので、画面B の変更が消える

画面A は email を触っていないのに、email を巻き戻しました。 これは失われた更新（ロストアップデート）と呼ばれ、エラーも出ずに起きます。

// 良い例: 更新するフィールドを明示させる
import "google/protobuf/field_mask.proto";
 
message UpdateUserRequest {
  User user = 1;
  google.protobuf.FieldMask update_mask = 2;  // "display_name" だけ更新する
  string etag = 3;                            // 取得時の版と違えば失敗させる
}

• update_mask — マスクに含まれるフィールドだけを更新します。含まれないフィールドは、たとえリクエストに値が入っていても無視します
• etag — 取得時に受け取った版を送り返させ、一致しなければ ABORTED を返します。「読んだ時から変わっていたら失敗する」を実現します

前章で扱った proto3 のゼロ値問題（0 が「未指定」なのか「0という値」なのか区別できない）も、 update_mask があれば起きません。「送られていないから更新しない」ではなく「マスクにあるから更新する」と判断するためです。

エラー設計 — 呼ぶ側が分岐できる形で返す

エラーは「返せば終わり」ではありません。 呼ぶ側がそのエラーを見て、次に何をするかを決められる必要があります。

// 悪い例: 成功も失敗も OK で返す
message CreateOrderResponse {
  bool success = 1;
  string message = 2;   // "在庫が足りません（SKU-123、残り2個）"
}

何が悪いのでしょうか。

正しくは、ステータスコードで分類し、詳細は構造化して返します。

// サーバー側（Go）
st := status.New(codes.FailedPrecondition, "insufficient stock")
st, _ = st.WithDetails(&errdetails.ErrorInfo{
    Reason:   "OUT_OF_STOCK",              // 安定した識別子。文言ではない
    Domain:   "shop.example.com",
    Metadata: map[string]string{"sku": "SKU-123", "available": "2"},
})
return nil, st.Err()

// 呼ぶ側は「コード」と「reason」で分岐できる
if status.Code(err) == codes.FailedPrecondition {
    // 在庫を確認する画面に誘導する、など
}

Reason は列挙できる安定した文字列にします。 表示用の文言は呼ぶ側が持ち、サーバーは「何が起きたか」だけを返す、という分担です。

ステータスコードの選び方

前章でコードと HTTP の対応は見ました。ここではどれを選ぶかを整理します。

新人が特に迷うのはこの3つの区別です。

• INVALID_ARGUMENT と FAILED_PRECONDITION — 「同じリクエストを後で送れば成功しうるか」で分けます。成功しうるなら FAILED_PRECONDITION です
• FAILED_PRECONDITION と ABORTED — FAILED_PRECONDITION は「状態を直すまで再試行するな」、ABORTED は「そのまま再試行してよい」です
• INTERNAL を安易に使わない — INTERNAL は「サーバーのバグ」を意味します。バリデーション漏れを全部 INTERNAL で返すと、監視上はすべてバグに見え、本物の障害が埋もれます

リトライできるかどうかを設計に含める

ネットワークは失敗します。呼ぶ側は必ずリトライを検討します。 ならば、リトライしてよいかどうかは、API の設計時に決めておくべきことです。

Get や List は自然に冪等なので何も要りません。問題は作成と更新です。

// 悪い例: 再送すると注文が2件できる
message CreateOrderRequest {
  Order order = 1;
}
 
// 良い例: 呼ぶ側が生成した ID で重複を防ぐ
message CreateOrderRequest {
  Order order = 1;
  string request_id = 2;  // クライアント生成の UUID。同じ ID の再送は1回だけ処理する
}

サーバーは request_id と処理結果を保存しておき、 同じ request_id が来たら処理せずに前回の結果を返します。 「応答が届かなかっただけで、実は成功していた」という最も厄介なケースを、これで吸収できます。

各 RPC について、次を決めて .proto のコメントに書きます。

Delete は特に決めておく価値があります。 2回目に NOT_FOUND を返すと、リトライした呼び出し側がエラー扱いします。 allow_missing フィールドを用意して「無ければ成功扱い」を選べるようにするのが一般的です。

タイムアウトやバックオフの具体的なやり方、リトライストームの怖さは、 第5部のマイクロサービス章で扱います。ここで押さえるのは1点です。

リトライ可能な API にするかどうかは、呼ぶ側ではなく、設計する側が決める。

バージョニング

パッケージにバージョンを入れます。

syntax = "proto3";
 
package shop.user.v1;
 
option go_package = "github.com/example/shop/gen/user/v1;userv1";

v1 は「1つ目のメジャーバージョン」であり、壊れる変更をする時にだけ上げるものです。 機能追加のたびに上げるものではありません。

まず、壊さずに済ませる

v2 を作るのは最後の手段です。ほとんどの変更は壊さずにできます。

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;   // 必ず 0 番に置く
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_SHIPPED = 2;
}

どうしても壊れる変更が必要な時

パッケージごと v2 を作って並走させます。 ただし、その前に「新しい RPC を足す」で済まないかを検討してください。

service UserService {
  // 2026-12-31 に削除予定。GetUserProfile を使うこと
  rpc GetUser(GetUserRequest) returns (GetUserResponse) {
    option deprecated = true;
  }
 
  rpc GetUserProfile(GetUserProfileRequest) returns (GetUserProfileResponse);
}

移行の手順は決まっています。

1. 新しい RPC を追加し、古い RPC に deprecated と削除予定日を書く
2. 古い RPC の呼び出しに、呼び出し元ごとのラベルを付けたメトリクスを仕込む
3. 呼んでいるチームに連絡する（メトリクスがあるので、誰に連絡すべきか分かります）
4. 呼び出し数がゼロの状態が数週間続いてから消す

時刻・金額・ID の扱い

型の選択だけで防げる事故があります。

// 悪い例
message Order {
  string created_at = 1;   // "2026/07/31 10:00" タイムゾーンは？ 形式は？
  double amount = 2;       // 浮動小数点で金額を扱っている
  int64 id = 3;            // 連番の ID
  string expires_in = 4;   // "30分" なのか "30" なのか
}

// 良い例
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/type/money.proto";
 
message Order {
  string id = 1;                                // 不透明な文字列（UUID など）
  google.protobuf.Timestamp create_time = 2;    // 絶対時刻。曖昧さがない
  google.type.Money amount = 3;                 // 通貨コード + 整数
  google.protobuf.Duration expires_after = 4;   // 期間は Duration
}

時刻

• 文字列にしない。 形式の解釈違い、タイムゾーンの欠落、パース失敗が必ず起きます
• Timestamp は UTC の絶対時刻です。表示のためのタイムゾーン変換は表示側の仕事です
• 「時刻」は Timestamp、「期間」は Duration、「日付だけ」（誕生日、締日）は google.type.Date を使い分けます
• フィールド名は create_time / update_time のように揃えます。created_at と create_time が混在する API は読みにくくなります

金額

浮動小数点（double / float）で金額を扱ってはいけません。

第3部のビットとバイト章で見た通り、0.1 は二進数で正確に表せません。 足し込むたびに誤差が積もり、帳簿が合わなくなります。合計金額が1円ずれる障害は、原因の特定に何日もかかります。

選択肢は2つです。

• google.type.Money（currency_code + units + nanos）を使う
• 最小単位の整数（円なら円、ドルならセント）と通貨コードを自分で持つ

どちらでも構いませんが、通貨コードを必ずセットで持ってください。 amount: 1000 だけでは、1000円なのか1000ドルなのか分かりません。

ID

ID に意味を持たせないでください。

悪い例: "2026-07-tokyo-0001"

一見便利ですが、次の日に破綻します。

• 拠点が統合されたら？ 年をまたいだら？ 桁が足りなくなったら？
• 呼ぶ側がID をパースし始めます。そうなった時点で、ID の形式は API の一部です。二度と変えられません

連番の int64 にも問題があります。

• 件数が漏れます（ID が 4213 なら、だいたい4千件だと分かります）
• 他人のデータを推測できます（id - 1 にアクセスしてみる、という攻撃が成立します）
• データベース章で扱う通り、分散データベースでは書き込みが1箇所に集中します

外部に出す ID は、UUID などの推測できない文字列にしてください。

REST でも同じ問題が起きる

ここまで gRPC で書いてきましたが、設計の論点は REST でも同じです。 表現の形が変わるだけで、考えることは変わりません。

REST そのものの考え方（リソースとメソッド）は第3部の Web と HTTP 章で扱っています。 「呼ぶ側が分岐できるエラーを返す」「後から足せる形にする」という原則は、プロトコルに依存しません。

設計レビューを先に受ける

この章の結論です。.proto のレビューは、実装を1行も書く前に受けてください。

実務では、次の順序で進めます。

1. 何を作るか・誰が呼ぶかを文章で書く（1ページで足りる）
2. .proto だけの PR を出す        ← ここでレビューを受ける
3. 承認されてから実装する
4. 実装の PR を出す

.proto だけの PR は差分が小さく、レビューする側も本質だけを見られます。 実装まで書いてから「この粒度だと使いにくい」と言われると、 指摘した側も気を遣い、直すべきものが直らないまま公開されます。

レビューで見るべきこと。

• 呼ぶ側のユースケースが書いてあるか。 誰が何のために呼ぶか
• その画面・処理は何回の呼び出しで完成するか
• 命名が既存の API と一貫しているか（Get / List / Create / Update / Delete）
• すべての RPC に専用の Request / Response があるか
• 一覧にページネーションがあるか。page_size の上限は決めたか
• 更新に field_mask と競合検出があるか
• 返しうるエラーが列挙されているか（コードと条件）
• リトライ可否と冪等性が決まっているか
• 時刻は Timestamp、金額は整数系、ID は不透明か
• 返しているデータに、呼ぶ側が持つべきでない個人情報がないか

const { user } = await client.getUser({ userId });
const { posts, nextPageToken } = await client.listPosts({ authorId: userId, pageSize: 20 });

実務の落とし穴まとめ

1. 内部のテーブル構造をそのまま公開する — 内部を変えるたびに API が壊れる
2. ループの中で RPC を呼ぶ設計 — N+1 の API 版。まとめて返す RPC を用意する
3. 動詞がバラバラ — Get / Fetch / Find の混在。使う側が毎回迷う
4. スカラー引数・ドメイン型を直接やり取り — 後からフィールドを足せない
5. offset ページネーション — 挿入でズレ、深いページで落ちる
6. page_size の上限を決めていない — 巨大な値を投げられて落ちる
7. 全体更新 API — 他人の変更を消す。field_mask と etag を使う
8. success: bool + メッセージ文字列でエラーを返す — 呼ぶ側が分岐できず、監視にも出ない
9. エラーメッセージに内部情報や個人情報 — 呼ぶ側のログに残り、回収できない
10. 金額を double、時刻を文字列、ID を連番 — 型の選択だけで防げた事故
11. 実装してからレビューを出す — もう直せない

まとめ

• API は一度公開すると変えられない。変えられないのは境界だけで、内部は自由に変えてよい
• 設計の起点は呼ぶ側のユースケース。DB のテーブル構造ではない
• 粒度は画面・ユースケース単位で数える。細かすぎれば N+1、粗すぎれば無駄と情報漏れ
• 命名は一貫性が最優先。Get / List / Create / Update / Delete に揃え、状態遷移は専用 RPC
• すべての RPC に専用の Request / Response を作る。後からフィールドを足すため
• 一覧は cursor 方式を基本に。page_size の上限とソート順の一意性を決める
• 更新は field_mask + etag。全体更新は他人の変更を消す
• エラーは呼ぶ側が分岐できる形で返す。コードで分類し、詳細は構造化する
• エラーメッセージに機密情報を入れない。trace_id を返してログで追う
• リトライ可否と冪等性は設計時に決める。Create には request_id
• 破壊的変更は避ける。どうしても必要なら新しい RPC を足して並走させ、メトリクスで移行を確認してから消す
• 時刻は Timestamp、金額は整数系、ID には意味を持たせない
• .proto だけの PR で先にレビューを受ける。実装してからでは直せない

公式ドキュメント

迷ったら一次情報に戻ってください。

章末問題

次の章では、この API の裏側でデータを保存する場所——データベースを扱います。