命名規則

数多くの 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 のコンセプトを明確に説明し(たとえば、何のインスタンスなのか)、他の関連するコンセプトと区別できる必要があります(たとえば、「alert」がルール、シグナル、通知のどれを意味するか)。
  • 一般的なプログラミング言語のキーワードと競合する可能性のある名前を使用する場合は、慎重に検討してください。このような名前を使用することはできますが、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 つ以上のネットワーク アドレスに解決可能な、(RFC 1035 に基づいて)構文的に有効な DNS 名にすることが推奨されます。公開 Google API のサービス名は、パターン xxx.googleapis.com に従います。たとえば、Google カレンダーのサービス名は calendar.googleapis.com です。

API が複数のサービスで構成されている場合、これらのサービスには見つけやすい名前を付けることが推奨されます。そのための 1 つの方法は、サービス名間で共通の接頭辞を共有することです。たとえば、サービス build.googleapis.combuildresults.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. など)を含むプロト パッケージ名と一致するしていることが必須です。次に例を示します。

package google.calendar.v3;

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

コレクション ID

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

インターフェース名

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

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

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

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

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

メソッド名

サービスにより、その IDL の仕様において、コレクションやリソースのメソッドに対応する 1 つ以上の RPC メソッドを定義できます。メソッド名は、UpperCamelCase で 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

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

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

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

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

メッセージ名

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

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

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

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

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

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

列挙型の名前

列挙型では、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_timeend_time のように、フィールド名の末尾を time にすることが推奨されます。

時間がアクティビティを指す場合、フィールド名は verb_time の形式を使用することが推奨されます(create_timeupdate_time など)。動詞には、created_timelast_updated_time などの過去時制を使用しないでください。

カレンダーや「日」や「月」などのコンセプトに関係なく時間の範囲を表すには、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() で定義するレスポンス メッセージ ListEventsResponse に含まれる、返されるリソースのリストを格納する繰り返しフィールドには、events という名前を付けることが必須となります。

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 の名前を使用することが必須です。

名前の略語

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

  • config(configuration)
  • id(identifier)
  • spec(specification)
  • stats(statistics)
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...