本指南適用於 REST API 和 RPC API，但主要聚焦於 gRPC API。gRPC API 使用通訊協定緩衝區定義其 API 介面，並使用 API 服務設定來設定其 API 服務，包括 HTTP 對應、記錄及監控功能。Google API 和 Cloud Endpoints gRPC API 會使用 HTTP 對應功能，將 JSON/HTTP 轉碼為通訊協定緩衝區/遠端程序呼叫 (RPC)。
隨著新的風格和設計模式獲採納及認可，本指南也會不斷修訂，與時俱進。正因如此，這份指南永遠沒有所謂的完稿版本，而且隨時都有增訂或修正的空間，以充分展現 API 設計的藝術與精妙之處。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-04 (世界標準時間)。"],[[["\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)"]]
