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:
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-09-04 (UTC)."],[[["\u003cp\u003eThis guide outlines Google's API design principles, used internally since 2014, and applicable to both REST and RPC APIs with a focus on gRPC.\u003c/p\u003e\n"],["\u003cp\u003eCloud Endpoints developers using gRPC APIs may find this guide particularly useful, although its use is not mandatory.\u003c/p\u003e\n"],["\u003cp\u003eThe guide covers various topics including resource-oriented design, standard methods, custom methods, standard fields, errors, design patterns, versioning, and more, referencing external links and AIPs.\u003c/p\u003e\n"],["\u003cp\u003eThis is a dynamic document that will be updated with new style and design patterns, but it will never be considered complete.\u003c/p\u003e\n"],["\u003cp\u003eKeywords like "MUST" and "SHOULD" are used with specific meanings as per RFC 2119, and are highlighted in \u003cstrong\u003ebold\u003c/strong\u003e within the guide.\u003c/p\u003e\n"]]],[],null,["# API design guide\n\n[Changelog](https://cloud.google.com/apis/design/changelog)\n\nIntroduction\n------------\n\nThis is a general design guide for networked APIs. It has been used inside\nGoogle since 2014 and is the guide that Google follows when designing\n[Cloud APIs](/apis/docs/overview) and other\n[Google APIs](https://github.com/googleapis/googleapis).\nThis design guide is shared here to inform outside developers and to make it\neasier for us all to work together.\n\n[Cloud Endpoints](/endpoints/docs/grpc) developers may find this\nguide particularly useful when designing gRPC APIs, and we strongly recommend\nsuch developers use these design principles. However,\nwe don't mandate its use. You can use Cloud\nEndpoints and gRPC without following the guide.\n\nThis guide applies to both REST APIs and RPC APIs, with specific focus on gRPC\nAPIs. gRPC APIs use [Protocol Buffers](/apis/design/proto3) to define their API surface\nand [API Service Configuration](https://github.com/googleapis/googleapis/blob/master/google/api/service.proto) to configure their API services, including\nHTTP mapping, logging, and monitoring. HTTP mapping features are used by Google\nAPIs and Cloud Endpoints gRPC APIs for JSON/HTTP to Protocol Buffers/RPC\n[transcoding](/endpoints/docs/transcoding).\n\nThis guide is a living document and additions to it will be made\nover time as new style and design patterns are adopted and approved. In that\nspirit, it is never going to be complete and there will always be ample\nroom for the art and craft of API design.\n\nConventions Used in This Guide\n------------------------------\n\nThe requirement level keywords \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\",\n\"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and\n\"OPTIONAL\" used in this document are to be interpreted as described in\n[RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).\n\nIn this document, such keywords are highlighted using **bold** font.\n\nSections\n--------\n\n### Resource-oriented Design\n\nFor information about implementing resource-oriented design for\nRPC and REST APIs, see [AIP-121](https://google.aip.dev/121).\n\n### Resource Names\n\nFor information about resource names,\nsee [AIP-122](https://google.aip.dev/122).\n\n### Standard Methods\n\nFor general information about methods, see [AIP-130](https://google.aip.dev/130).\n\nFor information about standard methods, see the following AIPs:\n\n- For `Get`, see [AIP-131](https://google.aip.dev/131)\n- For `List`, see [AIP-132](https://google.aip.dev/132)\n- For `Create`, see [AIP-133](https://google.aip.dev/133)\n- For `Update`, see [AIP-134](https://google.aip.dev/134)\n- For `Delete`, see [AIP-135](https://google.aip.dev/135)\n\n### Custom Methods\n\nFor information about custom methods, see [AIP-136](https://google.aip.dev/136).\n\n### Additional topics\n\nFor information about the following topics, see their related AIPs.\n\n- For **Standard fields** , see [AIP-148](https://google.aip.dev/148)\n- For **Errors** , see [AIP-193](https://google.aip.dev/193)\n- For **Design patterns** , see [AIP guidance on design patterns](https://google.aip.dev/general#design-patterns)\n- For **Inline API documentation** , see [AIP-192](https://google.aip.dev/192)\n- For **Using proto3** , see [the Syntax section of AIP-191](https://google.aip.dev/191#syntax)\n- For **Versioning** , see [AIP-185](https://google.aip.dev/185)\n- For **Backward compatibility** , see [AIP-180](https://google.aip.dev/180)\n- For **File structure** , see [the File Layout section of AIP-191](https://google.aip.dev/191#file-layout)\n- For a **Glossary** of terms, see [AIP-9](https://google.aip.dev/9)\n- For **Naming conventions** , see [AIP-190](https://google.aip.dev/190)\n\nFor information about the following topics, see their related pages in this guide.\n\n- [Directory Structure](https://cloud.google.com/apis/design/directory_structure)"]]
