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
- Ressourcennamen
- Standardmethoden
- Benutzerdefinierte Methoden
- Standardfelder
- Fehler
- Namenskonventionen
- Designmuster
- Dokumentation
- Proto3 verwenden
- Versionsverwaltung
- Kompatibilität
- Verzeichnisstruktur
- Dateistruktur
- Glossar