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 eines ressourcenorientierten Designs für RPC- und REST-APIs finden Sie unter AIP-121.
Ressourcennamen
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:
Benutzerdefinierte Methoden
Informationen zu benutzerdefinierten Methoden finden Sie unter AIP-136.
Weitere Informationen
Informationen zu den folgenden Themen finden Sie in den zugehörigen AIPs.
- Standardfelder finden Sie unter AIP-148.
- Fehler: AIP-193
- Designmuster: AIP-Leitfaden zu Designmustern
- Inline-API-Dokumentation finden Sie unter AIP-192.
- Weitere Informationen zur Verwendung von Proto3 finden Sie im Syntaxabschnitt von AIP-191.
- Informationen zur Versionierung finden Sie unter AIP-185.
- Informationen zur Abwärtskompatibilität finden Sie unter AIP-180.
- Informationen zur Dateistruktur finden Sie im Abschnitt „Dateilayout“ von AIP-191.
- Ein Glossar mit Begriffen finden Sie unter AIP-9.
Informationen zu den folgenden Themen finden Sie auf den entsprechenden Seiten in diesem Leitfaden.