Leitfaden zum API-Design

Änderungslog

Einführung

Dies ist eine allgemeine Designanleitung für Netzwerk-APIs. Sie wird Google-intern seit 2014 zum Erstellen von Cloud APIs und anderen Google APIs verwendet. Diese Designanleitung richtet sich an externe Entwickler und soll die Zusammenarbeit erleichtern.

Cloud-Endpunkte-Entwickler finden dieses Handbuch möglicherweise besonders nützlich beim Entwerfen von gRPC-APIs. Wir empfehlen diesen Entwicklern dringend, diese Entwurfsprinzipien zu verwenden. Die Verwendung ist jedoch nicht obligatorisch. Sie können Cloud Endpoints und gRPC auch verwenden, ohne diese Anleitung zu befolgen.

Die Anleitung gilt für REST APIs und RPC APIs gleichermaßen, wobei schwerpunktmäßig gRPC APIs behandelt werden. gRPC APIs definieren ihre API-Oberfläche mit Protokollpuffern. Anhand der API-Dienstkonfiguration werden die API-Dienste einschließlich HTTP-Zuordnung, Logging und Monitoring eingerichtet. Die HTTP-Zuordnungsfunktionen werden von Google APIs und Cloud Endpoints gRPC APIs für die Transcodierung von JSON/HTTP in Protocol Buffers/RPC verwendet.

Diese Anleitung ist ein dynamisches Dokument, dem im Lauf der Zeit infolge der Einführung und Genehmigung neuer Stil- und Designmuster Ergänzungen hinzugefügt werden. Sie ist somit nie abgeschlossen und wird immer neue Informationen und Anregungen für das API-Design bieten.

In diesem Leitfaden verwendete Konventionen

Wie die in diesem Dokument verwendeten Schlüsselwörter "MUSS", "DARF NICHT", "ERFORDERLICH", "WIRD", "WIRD NICHT", "SOLLTE", "SOLLTE NICHT", "EMPFOHLEN", "KÖNNEN" und "OPTIONAL" zu interpretieren sind, lesen Sie unter "RFC 2119".

Im vorliegenden Dokument werden diese Schlüsselwörter fett hervorgehoben.

Abschnitte

Ressourcenorientiertes Design

Informationen zur Implementierung des ressourcenorientierten Designs für RPC- und REST-APIs finden Sie unter AIP-121.

Ressourcennamen

Weitere Informationen zu Ressourcennamen finden Sie unter AIP-122.

Standardmethoden

Allgemeine Informationen zu Methoden finden Sie unter AIP-130.

Informationen zu Standardmethoden finden Sie in den folgenden AIPs:

  • Informationen zu Get finden Sie unter AIP-131.
  • Informationen zu List finden Sie unter AIP-132.
  • Informationen zu Create finden Sie unter AIP-133.
  • Informationen zu Update finden Sie unter AIP-134.
  • Informationen zu Delete finden Sie unter AIP-135.

Benutzerdefinierte Methoden

Informationen zu benutzerdefinierten Methoden finden Sie unter AIP-136.

Weitere Informationen

Informationen zu den folgenden Themen finden Sie in den entsprechenden AIPs.

Informationen zu den folgenden Themen finden Sie auf den entsprechenden Seiten in diesem Leitfaden.

Weiter
Verzeichnisstruktur