命名規則

数多くの 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 つ以上のネットワーク アドレスに解決可能な、(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. など)を持つ proto パッケージ名と一致する必要があります。例:

package google.calendar.v3;

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

コレクション ID

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

インターフェース名

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 メソッドを定義できます。メソッド名は、大文字のキャメルケースで、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;
    }
    

ラッパー

0UNSPECIFIED 以外の意味を持つ 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_errorerror_reason にする必要があります。
  • cpu_usage_at_time_of_failurefailure_time_cpu_usage にする必要があります。

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

  • items_collectedcollected_items にする必要があります。
  • objects_importedimported_objects にする必要があります。

繰り返しフィールド名

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

時間と期間

タイムゾーンやカレンダーに関係なく特定の時点を表すには、google.protobuf.Timestamp を使用する必要があります。また、start_timeend_time のように、フィールド名の末尾を time にする必要があります。

時刻がアクティビティを指す場合、フィールド名は、create_timeupdate_time など、verb_time の形式にすることが推奨されます。created_timelast_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 の名前を使用する必要があります。

名前の略語

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

  • config(configuration)
  • id(identifier)
  • spec(specification)
  • stats(statistics)