命名規則

数多くの API で長期にわたって一貫したデベロッパー エクスペリエンスを提供するために、API で使用されるすべての名前は、次の特徴を備えていることが推奨されます。

  • シンプル
  • 直感的
  • 整合性

これには、インターフェース、リソース、コレクション、メソッド、メッセージの名前が含まれます。

多くの開発者は英語が母語ではないため、大部分の開発者が API を簡単に理解できるようにすることが、これらの命名規則の 1 つの目標です。そのためには、メソッドやリソースに名前を付けるときに、シンプルで整合性のある少ない語彙を使用することが推奨されます。

  • API で使用される名前は、正しいアメリカ英語にすることが推奨されます。たとえば、licence ではなく license、colour ではなく color などです。
  • 用語が長い場合は、簡略化するために、一般に使用されている短縮形や略語を使用することもできます。たとえば、Application Programming Interface よりも API という表現が推奨されます。
  • 必要に応じて、直感的で慣れ親しんだ用語を使用します。たとえば、リソースを削除（破棄）する場合、erase よりも delete が推奨されます。
  • 同じコンセプト（API 全体で共有されるコンセプトも含めて）には同じ名前や用語を使用します。
  • 名前の多重定義を回避します。異なるコンセプトには異なる名前を使用します。
  • API のコンテキストや Google API の大規模なエコシステム内で複数の意味を持つ、過度に一般的な名前は使用しないでください。そのような名前は、API のコンセプトについて誤解を招く可能性があります。API のコンセプトを正確に説明する具体的な名前を選択します。これは、リソースなど、API の一次要素を定義する名前にとっては特に重要です。すべての名前は他の名前のコンテキストにおいて評価する必要があるため、使用できない名前を定義したリストはありません。instance、info、service は、過去に問題があった名前の例です。選択する名前は、API のコンセプトを明確に説明し（たとえば、何のインスタンスなのか）、他の関連するコンセプトと区別することが推奨されます（たとえば、「アラート」はルール、シグナル、通知のどれを意味するか）。
  • 一般的なプログラミング言語のキーワードと競合する可能性のある名前を使用する場合は、慎重に検討してください。このような名前を使用することはできますが、API の審査で追加的な調査が発生する原因になることがあります。このような名前はなるべく使用しないでください。

プロダクト名

プロダクト名とは、Google Calendar API などの API のプロダクト マーケティング名のことです。API、UI、ドキュメント、利用規約、請求明細、商用契約などで一貫したプロダクト名を使用する必要があります。Google API では、プロダクト チームやマーケティング チームが承認したプロダクト名を使用する必要があります。

次の表は、関連するすべての API 名とその整合性の例を示しています。それぞれの名前とその規則の詳細については、このページの下部をご覧ください。

API 名 例
プロダクト名 Google Calendar API
サービス名 calendar.googleapis.com
パッケージ名 google.calendar.v3
インターフェース名 google.calendar.v3.CalendarService
ソース ディレクトリ //google/calendar/v3
API 名 calendar

サービス名

サービス名は、1 つ以上のネットワーク アドレスに解決可能な、構文的に有効な DNS 名（RFC 1035 に基づく）にすることが推奨されます。公開 Google API のサービス名は、パターン xxx.googleapis.com に従います。たとえば、Google カレンダーのサービス名は calendar.googleapis.com です。

API が複数のサービスで構成されている場合、これらのサービスには見つけやすい名前を付けることが推奨されます。そのための 1 つの方法は、サービス名間で共通の接頭辞を共有することです。たとえば、サービス build.googleapis.com と buildresults.googleapis.com は、両方とも Google Build API の一部であるサービスです。

パッケージ名

API .proto ファイルで宣言されたパッケージ名は、プロダクト名やサービス名と一貫したものにすることが推奨されます。パッケージ名は、単数および複数形のコンポーネント名が混在するのを避けるために、単一のコンポーネント名を使用することが推奨されます。パッケージ名にアンダースコアは使用できません。バージョン管理された API のパッケージ名の末尾は、バージョンにする必要があります。例:

// Google Calendar API
package google.calendar.v3;

Google Watcher API など、サービスに直接関連付けられていない抽象化 API では、プロダクト名との整合性のある proto パッケージ名を使用することが推奨されます。

// Google Watcher API
package google.watcher.v1;

API の.proto ファイルで指定する Java パッケージ名は、標準の Java パッケージ名接頭辞（com.、edu.、net. など）を持つ proto パッケージ名と一致する必要があります。次に例を示します。

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

コレクション ID

コレクション ID は複数形、lowerCamelCase、アメリカ英語のスペルとセマンティクスを使用することが推奨されます。たとえば、events、children、deletedEvents などです。

インターフェース名

pubsub.googleapis.com などのサービス名との混同を避けるために、「インターフェース名」という用語は、.proto ファイル内で service を定義するときに使用される名前を指します。

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

サービス名は一連の API の実際の実装への参照であり、インターフェース名は API の抽象的な定義を指すと考えることができます。

インターフェース名には、Calendar や blob などの直感的な名詞を使用することが推奨されます。この名前は、プログラミング言語とそのランタイム ライブラリ（ファイルなど）の確立されたコンセプトのいずれとも競合しないようにしてください。

可能性は低いものの、インターフェース名が API 内の別の名前と競合する場合は、曖昧さを回避するために、接尾辞（Api や Service など）を使用することが推奨されます。

メソッド名

サービスにより、その IDL の仕様において、コレクションやリソースのメソッドに対応する 1 つ以上の RPC メソッドを定義できます。メソッド名は、大文字のキャメルケースで、VerbNoun の命名規則に従うことが推奨されます。通常、名詞はリソースタイプを表します。

動詞 名詞 メソッド名 リクエスト メッセージ レスポンス メッセージ
List Book ListBooks ListBooksRequest ListBooksResponse
Get Book GetBook GetBookRequest Book
Create Book CreateBook CreateBookRequest Book
Update Book UpdateBook UpdateBookRequest Book
Rename Book RenameBook RenameBookRequest RenameBookResponse
Delete Book DeleteBook DeleteBookRequest google.protobuf.Empty

メソッド名の動詞部分には、質問を目的とした直説法ではなく、指示や命令を目的とした命令法を使用する必要があります。

標準メソッドの場合、メソッド名の名詞部分は、List を除くすべてのメソッドに対して単数形であることが必要です。また、List では複数形にする必要があります。カスタム メソッドでは、必要に応じて単数形または複数形の名詞を指定できます。バッチメソッドでは、複数形の名詞を使用することが必須です。

API 内のサブリソースについて質問する動詞は、直説法で表現されることがよくあるため、混乱が発生しやすくなります。たとえば、書籍の作成を API に指示する場合は明確に（命令法で）CreateBook ですが、書籍のサイト運営者の状態を API に尋ねる場合は、IsBookPublisherApproved や NeedsPublisherApproval など、直説法を使用する場合があります。このような場合で命令法にするには、「check」（CheckBookPublisherApproved）や「validate」（ValidateBookPublisher）などのコマンドを使用します。

メソッド名には、前置詞（For、With、At、To など）を含めないことが推奨されます。一般に、メソッド名に前置詞が含まれる場合、既存のメソッドにフィールドを追加する必要がある状況で新しいメソッドが使用されているか、メソッドに異なる動詞を使用する必要があることを示します。

たとえば、CreateBook メッセージがすでに存在し、CreateBookFromDictation の追加を検討している場合、代わりに TranscribeBook メソッドを検討します。

メッセージ名

メッセージ名は短く簡略であることが推奨されます。不要な言葉や冗長な文章は避けてください。形容詞を外した状態で対応するメッセージが存在しない場合、その形容詞はたいてい省略できます。たとえば、SharedProxySettings の Shared は、共有されていないプロキシ設定がなければ不要です。

メッセージ名には前置詞（With、For など）を含めないことが推奨されます。通常、前置詞を含むメッセージ名は、そのメッセージのオプション フィールドを使うと、より的確に表現できます。

リクエスト メッセージとレスポンス メッセージ

RPC メソッドのリクエスト メッセージとレスポンス メッセージには、メソッド名にちなんだ名前を付けて、その後にそれぞれ接尾辞 Request や Response を続けることが推奨されます。ただし、メソッドのリクエストやレスポンスが次のタイプである場合は、その限りではありません。

  • 空のメッセージ（google.protobuf.Empty を使用）
  • リソースタイプ
  • オペレーションを表すリソース

これは通常、標準メソッド Get、Create、Update、Delete で使用されるリクエストまたはレスポンスに適用されます。

列挙型の名前

列挙型では、UpperCamelCase の名前を使用する必要があります。

列挙値には、CAPITALIZED_NAMES_WITH_UNDERSCORES を使用する必要があります。各列挙値は、カンマではなくセミコロンで終わる必要があります。最初の値は、列挙値が明示的に指定されていない場合に返されるため、ENUM_TYPE_UNSPECIFIED という名前にすることが推奨されます。

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

ラッパー

0 値が UNSPECIFIED 以外の意味を持つ proto2 列挙型をカプセル化するメッセージには、名前に接尾辞 Value を付け、value という名前の単一フィールドを含めることが推奨されます。

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

フィールド名

.proto ファイルのフィールド定義では、lower_case_underscore_separated_names を使用する必要があります。これらの名前は、プログラミング言語ごとに生成されたコードのネイティブ命名規則にマッピングされます。

フィールド名には、次に示すように、前置詞（for、during、at など）を含めないことが推奨されます。

  • reason_for_error は error_reason にします。
  • cpu_usage_at_time_of_failure は failure_time_cpu_usage にします。

フィールド名では、次に示すように、後置形容詞（名詞の後に配置される修飾語）を使用しないことも推奨されます。

  • items_collected は collected_items にします。
  • objects_imported は imported_objects にします。

繰り返しフィールド名

API の繰り返しフィールドでは、適切な複数形を使用する必要があります。このことは、既存の Google API の規則や外部開発者の一般的な想定と一致します。

時間と期間

タイムゾーンやカレンダーに関係なく特定の時点を表すには、google.protobuf.Timestamp を使用することが推奨されます。また、start_time や end_time のように、フィールド名の末尾を time にすることが推奨されます。

時刻がアクティビティを指す場合、フィールド名は、create_time や update_time など、verb_time の形式にすることが推奨されます。created_time や last_updated_time のようなの過去時制は使用しないでください。

カレンダーや「日」や「月」などのコンセプトに関係なく、2 つの時点間の期間を表すには、google.protobuf.Duration を使用することが推奨されます。

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

実時間、期間、遅延、レイテンシなど、レガシーや互換性の理由から整数型を使用して時間関連フィールドを表現する必要がある場合、フィールド名は次の形式にする必要があります。

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

レガシーや互換性の理由から、文字列型を使用してタイムスタンプを表す必要がある場合、フィールド名に単位の接尾辞を含めないことが推奨されます。文字列表現では、「2014-07-30T10:43:17Z」などの RFC 3339 形式を使用することが推奨されます。

日付と時刻

タイムゾーンや時刻とは無関係の日付の場合は、google.type.Date を使用し、接尾辞 _date を含めることが推奨されます。日付を文字列として表す必要がある場合は、ISO 8601 の日付形式 YYYY-MM-DD（2014-07-30 など）にすることが推奨されます。

タイムゾーンと日付とは無関係な時刻の場合は、google.type.TimeOfDay を使用し、接尾辞 _time を含めることが推奨されます。時刻を文字列として表す必要がある場合は、ISO 8601 の 24 時間形式の HH:MM:SS [.FFF] にすることが推奨されます（14:55:01.672 など）。

message StoreOpening {
  google.type.Date opening_date = 1;
  google.type.TimeOfDay opening_time = 2;
}

在庫数

整数型で表される在庫数には、測定単位が含まれている必要があります。

xxx_{bytes|width_pixels|meters}

在庫数が品目の数である場合、フィールドには node_count のように接尾辞 _count を含めることが推奨されます。

リストフィルタ フィールド

List メソッドによって返されるリソースのフィルタリングが API でサポートされている場合、フィルタ式を含むフィールドには filter という名前を付けることが推奨されます。次に例を示します。

message ListBooksRequest {
  // The parent resource name.
  string parent = 1;

  // The filter expression.
  string filter = 2;
}

リスト レスポンス

List メソッドのレスポンス メッセージに含まれる、リソースのリストを格納するフィールドの名前は、リソース名自体の複数形である必要があります。たとえば、メソッド CalendarApi.ListEvents() は、返されるリソースのリストに対して、events という繰り返しフィールドを含むレスポンス メッセージ ListEventsResponse を定義する必要があります。

service CalendarApi {
  rpc ListEvents(ListEventsRequest) returns (ListEventsResponse) {
    option (google.api.http) = {
      get: "/v3/{parent=calendars/*}/events";
    };
  }
}

message ListEventsRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

message ListEventsResponse {
  repeated Event events = 1;
  string next_page_token = 2;
}

キャメルケース

フィールド名と列挙型の値を除いて、.proto ファイル内のすべての定義では、Google Java Style で定義されているように、UpperCamelCase の名前を使用する必要があります。

名前の略語

config や spec など、ソフトウェア デベロッパーの間でよく知られている略語については、API 定義ではフルスペルではなく略語を使用することが推奨されます。これにより、ソースコードの読み書きが容易になります。正式なドキュメントでは、フルスペルを使用することが推奨されます。例:

  • config（configuration）
  • id（identifier）
  • spec（specification）
  • stats（statistics）
前へ
エラー
次へ
設計パターン