Namenskonventionen

Um Entwicklern auf lange Sicht für möglichst viele APIs eine konsistente Umgebung zu bieten, sollten alle für eine API verwendeten Namen Folgendes sein:

  • einfach
  • intuitiv
  • konsistent

Dies gilt für die Namen von Schnittstellen, Ressourcen, Sammlungen, Methoden und Nachrichten.

Da viele Entwickler keine englischen Muttersprachler sind, dienen diese Namenskonventionen unter anderem dem Zweck, eine API für möglichst viele Entwickler verständlich zu machen. Das Vokabular für die Namen von Methoden und Ressourcen sollte daher einfach, konsistent und auf einen überschaubaren Wortschatz beschränkt sein.

  • Die in APIs verwendeten Namen sollten in korrektem amerikanischem Englisch geschrieben sein. Verwenden Sie beispielsweise "license" (statt "licence") und "color" (statt "colour").
  • Um Bezeichnungen kurz zu halten, können Sie bei langen Namen deren gängige Kurzform bzw. Akronym verwenden. Das Akronym "API" ist beispielsweise gegenüber der Langform "Application Programming Interface" zu bevorzugen.
  • Verwenden Sie eine möglichst intuitive, vertraute Terminologie. Um beispielsweise das Entfernen (und Zerstören) einer Ressource zu beschreiben, wird "delete" gegenüber "erase" bevorzugt.
  • Verwenden Sie pro Konzept durchgängig denselben Namen oder Begriff. Dies gilt auch für Konzepte, die für mehrere APIs genutzt werden.
  • Vermeiden Sie übermäßig mehrdeutige Namen. Verwenden Sie unterschiedliche Namen für unterschiedliche Konzepte.
  • Vermeiden Sie zu allgemeine Namen, die im Kontext der API und der gesamten Umgebung der Google APIs nicht eindeutig sind. Sie können zu Missverständnissen bei API-Konzepten führen. Wählen Sie stattdessen spezifische Namen aus, die das API-Konzept genau beschreiben. Dies ist insbesondere bei Namen wichtig, mit denen API-Elemente der ersten Ordnung wie etwa Ressourcen definiert werden. Es gibt keine verbindliche Liste von zu vermeidenden Namen, da jeder Name im Kontext von anderen Namen bewertet werden muss. Die Bezeichnungen "instance", "info" und "service" führen beispielsweise oft zu Problemen. Die ausgewählten Namen sollten das API-Konzept eindeutig beschreiben (zum Beispiel: Instanz von was?) und es von anderen relevanten Konzepten unterscheiden, etwa klar erkennen lassen, ob sich beispielsweise "alert" auf die Regel, das Signal oder die Benachrichtigung bezieht.
  • Achten Sie darauf, dass die gewählten Namen nicht mit Schlüsselwörtern in gängigen Programmiersprachen in Konflikt stehen Sie können solche Namen verwenden, müssen jedoch bei der API-Überprüfung damit rechnen, dass die Namen eingehender untersucht werden. Verwenden Sie diese daher überlegt und sparsam.

Produktnamen

Mit Produktnamen sind die Marketingnamen von APIs wie Google Calendar API gemeint. Produktnamen müssen in APIs, UIs, Dokumentation, Nutzungsbedingungen, Abrechnungen, Geschäftsverträgen usw. einheitlich verwendet werden. Google APIs müssen Produktnamen verwenden, die von den Produkt- und Marketingteams genehmigt wurden.

In der folgenden Tabelle sehen Sie Beispiele aller zugehörigen API-Namen und deren Konsistenz. Weiter unten auf dieser Seite wird näher auf die jeweiligen Namen und Konventionen eingegangen.

API-Name Beispiel
Produktname Google Calendar API
Dienstname calendar.googleapis.com
Paketname google.calendar.v3
Schnittstellenname google.calendar.v3.CalendarService
Quellverzeichnis //google/calendar/v3
API-Name calendar

Dienstnamen

Dienstnamen sollten (gemäß RFC 1035) syntaktisch gültige DNS-Namen sein, die sich in eine oder mehrere Netzwerkadressen auflösen lassen. Die Dienstnamen öffentlicher Google-APIs folgen dem Muster xxx.googleapis.com. Der Dienstname von Google Kalender lautet beispielsweise calendar.googleapis.com.

Wenn eine API aus mehreren Diensten besteht, sollten diese so benannt werden, dass sie leicht auffindbar sind. Eine Möglichkeit besteht darin, den Dienstnamen dasselbe Präfix voranzustellen. Beispielsweise sind die Dienste build.googleapis.com und buildresults.googleapis.com beide Teil der Google Build API.

Paketnamen

In den .proto-Dateien der API deklarierte Paketnamen sollten mit Produkt- und Dienstnamen konsistent sein. Paketnamen sollten einzelne Komponentennamen verwenden, um gemischte Singular- und Pluralformen zu vermeiden. Paketnamen dürfen keine Unterstriche enthalten. Paketnamen für versionierte APIs müssen mit der Version enden. Beispiel:

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

Für eine abstrakte API, die nicht direkt mit einem Dienst verknüpft ist, wie etwa die Google Watcher API, sollten mit dem Produktnamen konsistente Proto-Paketnamen verwendet werden.

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

In den .proto-Dateien der API angegebene Java-Paketnamen müssen durch ein Standardpräfix für Java-Paketnamen wie com., edu., net. usw. an die Proto-Paketnamen angepasst werden. Beispiel:

package google.calendar.v3;

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

Sammlungs-IDs

Sammlungs-IDs sollten im Plural und in der Form lowerCamelCase angegeben werden sowie die Schreibweise und Semantik des amerikanischen Englisch verwenden. Beispiel: events, children oder deletedEvents.

Schnittstellennamen

Zur Vermeidung von Verwechslungen mit Dienstnamen wie pubsub.googleapis.com bezieht sich der Begriff Schnittstellenname auf den Namen, mit dem ein service in einer .proto-Datei definiert wird:

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

Der Dienstname ist sozusagen ein Verweis auf die eigentliche Implementierung einer Reihe von APIs, während sich der Schnittstellenname auf die abstrakte Definition einer API bezieht.

Für den Schnittstellennamen sollte ein intuitives Substantiv wie "Calendar" oder "Blob" verwendet werden. Der Name sollte nicht mit bekannten Konzepten in Programmiersprachen und deren Laufzeitbibliotheken wie etwa "File" in Konflikt stehen.

Falls in Ausnahmefällen dennoch ein Konflikt zwischen einem Schnittstellennamen und einem anderen Namen in der API auftritt, sollte zur Unterscheidung ein Suffix wie z. B. Api oder Service angehängt werden.

Methodennamen

Ein Dienst kann in seiner IDL-Spezifikation eine oder mehrere RPC-Methoden definieren, die Methoden für Sammlungen und Ressourcen entsprechen. Die Methodennamen sollten der Namenskonvention VerbNoun in Camel-Case-Schreibweise mit großem Anfangsbuchstaben folgen, wobei das Substantiv in der Regel der Ressourcentyp ist.

Verb Substantiv Methodenname Anfragenachricht Antwortnachricht
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

Der Verbteil des Methodennamens sollte im Imperativ stehen, d. h. in der Befehlsform und nicht im Indikativ, der für Fragen herangezogen wird.

Bei Standardmethoden muss der Substantivteil des Methodennamens für alle Methoden außer für List Singular sein. Für List muss er Plural sein. Bei benutzerdefinierten Methoden kann das Substantiv je nach Bedarf Singular oder Plural sein. Batchmethoden müssen das Substantitiv im Plural verwenden.

Dies wird leicht verwechselt, wenn mit dem Verb eine Frage zu einer Unterressource der API gestellt wird, da diese häufig im Indikativ ausgedrückt wird. Die Anfrage an die API zum Erstellen eines Buches lautet beispielsweise eindeutig CreateBook (im Imperativ). Wenn Sie aber die API nach dem Status des Herausgebers des Buches fragen, kann der Indikativ verwendet werden, z. B. IsBookPublisherApproved oder NeedsPublisherApproval. Damit in solchen Situationen der Imperativ verwendet wird, empfiehlt sich die Verwendung von Befehlen wie "check" (CheckBookPublisherApproved) und "validate" (ValidateBookPublisher).

Methodennamen dürfen keine Präpositionen wie "for", "with", "at" oder "to" enthalten. Im Allgemeinen zeigen Methodennamen mit Präpositionen an, dass eine neue Methode verwendet wird, bei der stattdessen ein Feld zu einer vorhandenen Methode hinzugefügt werden sollte oder die Methode ein eindeutiges Verb verwenden sollte.

Wenn beispielsweise bereits eine CreateBook-Nachricht vorhanden ist und Sie CreateBookFromDictation hinzufügen möchten, sollten Sie stattdessen die Verwendung einer TranscribeBook-Methode in Betracht ziehen.

Nachrichtennamen

Die Namen der Nachrichten sollten kurz und prägnant sein. Vermeiden Sie unnötige oder überflüssige Wörter. Adjektive können oft weggelassen werden, wenn keine entsprechende Nachricht ohne Adjektiv vorhanden ist. Beispielsweise ist Shared in SharedProxySettings nicht erforderlich, wenn keine nicht freigegebenen Proxyeinstellungen vorhanden sind.

Nachrichtennamen dürfen keine Präpositionen wie "with" oder "for" enthalten. Im Allgemeinen werden Nachrichtennamen mit Präpositionen durch optionale Felder in der Nachricht besser dargestellt.

Anfrage- und Antwortnachrichten

Die Anfrage- und Antwortnachrichten für RPC-Methoden sollten nach den Methodennamen mit dem Suffix Request bzw. Response benannt werden. Ausgenommen davon sind folgende Typen von Methodenanfragen oder -antworten:

  • eine leere Nachricht (verwenden Sie google.protobuf.Empty)
  • Ressourcentypen
  • Ressourcen, die einen Vorgang darstellen

Dies gilt in der Regel für Anfragen oder Antworten, die in den Standardmethoden Get, Create, Update und Delete verwendet werden.

ENUM-Namen

Für ENUM-Typen müssen Camel-Case-Namen mit großem Anfangsbuchstaben verwendet werden.

ENUM-Werte müssen in GROSSBUCHSTABEN_MIT_UNTERSTRICHEN formuliert werden. Jeder ENUM-Wert muss mit einem Semikolon, also nicht mit einem Komma enden. Der erste Wert sollte als ENUM_TYPE_UNSPECIFIED benannt werden, da er zurückgegeben wird, wenn kein expliziter ENUM-Wert festgelegt wurde.

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

Wrapper

Nachrichten, die proto2-ENUM-Typen enthalten, bei denen der Wert 0 eine andere Bedeutung als UNSPECIFIED hat, sollten mit dem Suffix Value benannt werden und ein einzelnes Feld namens value haben.

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

Feldnamen

Felddefinitionen in den .proto-Dateien müssen namen_in_kleinbuchstaben_mit_unterstrichen verwenden. Diese Namen werden im generierten Code der nativen Namenskonvention der jeweiligen Programmiersprache zugeordnet.

Feldnamen sollten keine Präpositionen wie "for", "during" oder "at" enthalten. Beispiel:

  • reason_for_error sollte stattdessen error_reason sein
  • cpu_usage_at_time_of_failure sollte stattdessen failure_time_cpu_usage sein

Feldnamen sollten keine postpositiven Adjektive (Modifikatoren hinter dem Nomen) verwenden. Beispiele:

  • items_collected sollte stattdessen collected_items sein
  • objects_imported sollte stattdessen imported_objects sein

Namen wiederkehrender Felder

Für die Namen wiederkehrender Felder in APIs muss die richtige Pluralform verwendet werden. Dies entspricht der Konvention bestehender Google APIs und der allgemeinen Erwartung externer Entwickler.

Zeit und Dauer

Zur Darstellung eines von Zeitzonen oder Kalendern unabhängigen Zeitpunkts sollte google.protobuf.Timestamp verwendet werden. Der Feldname sollte mit time enden, z. B. start_time und end_time.

Wenn sich der Zeitpunkt auf eine Aktivität bezieht, sollte der Feldname in der Form verb_time festgelegt werden, beispielsweise create_time, update_time. Vermeiden Sie die Verwendung der Vergangenheitsform für das Verb, z. B. created_time oder last_updated_time.

Wenn ein Zeitraum zwischen zwei Zeitpunkten unabhängig von einem Kalender und von Konzepten wie "Tag" oder "Monat" dargestellt werden soll, sollte google.protobuf.Duration verwendet werden.

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

Wenn Sie zeitbezogene Felder etwa zur Angabe von Ortszeit, Dauer, Verzögerung oder Latenz für ältere Versionen oder aus Kompatibilitätsgründen mit einem Ganzzahltyp darstellen möchten, müssen die Feldnamen das folgende Format haben:

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

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

Wenn Sie den Zeitstempel für ältere Versionen oder aus Kompatibilitätsgründen als String darstellen möchten, sollten die Feldnamen kein Suffix für die Zeiteinheit enthalten. Die Stringdarstellung sollte im RFC 3339-Format erfolgen, zum Beispiel "2014-07-30T10:43:17Z".

Datum und Uhrzeit

Für Datumsangaben, die unabhängig von Zeitzone und Tageszeit sind, sollte google.type.Date verwendet werden und sie sollten das Suffix _date haben. Wenn ein Datum als String dargestellt werden muss, sollte das ISO 8601-Datumsformat JJJJ-MM-TT verwendet werden, zum Beispiel: 2014-07-30.

Für Tageszeiten, die unabhängig von Zeitzonen und Datum sind, sollte google.type.TimeOfDay verwendet werden und sie sollten das Suffix _time haben. Wenn eine Tageszeit als String dargestellt werden muss, sollte sie im 24-Stunden-Format HH:MM:SS [.FFF] nach ISO 8601 vorliegen, z. B. 14:55:01.672.

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

Mengen

Bei Mengen, die durch einen Ganzzahltyp dargestellt werden, muss die Maßeinheit angegeben werden.

xxx_{bytes|width_pixels|meters}

Wenn die Menge eine Stückzahl ist, sollte an das Feld das Suffix _count angehängt werden, z. B. node_count.

Listenfilterfeld

Wenn eine API das Filtern von Ressourcen unterstützt, die von der Methode List zurückgegeben werden, sollte das Feld mit dem Filterausdruck filter heißen. Beispiel:

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

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

Listenantwort

Der Name des Felds in der Antwortnachricht der Methode List, die eine Liste der Ressourcen enthält, muss eine Pluralform des Ressourcennamens selbst sein. Beispielsweise muss eine Methode CalendarApi.ListEvents() eine Antwortnachricht ListEventsResponse mit einem wiederkehrenden Feld namens events für die Liste der zurückgegebenen Ressourcen definieren.

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;
}

Camel-Case-Schreibweise

Mit Ausnahme von Feldnamen und ENUM-Werten müssen alle Definitionen in .proto-Dateien Namen in Camel-Case-Schreibweise mit großem Anfangsbuchstaben verwenden, wie durch den Google-Java-Stil definiert.

Namensabkürzung

Für unter Softwareentwicklern bekannte und gängige Namensabkürzungen wie config und spec sollten in API-Definitionen statt der ausgeschriebenen Namen die Abkürzungen verwendet werden. Dies erleichtert das Lesen und Schreiben des Quellcodes. In formaler Dokumentation sollten die Namen vollständig ausgeschrieben werden. Beispiele:

  • config (configuration)
  • id (identifier)
  • spec (specification)
  • stats (statistics)
Zurück
Fehler
Weiter
Designmuster