This is a general design guide for networked APIs. It has been used inside
Google since 2014 and is the guide that Google follows when designing
Cloud APIs and other
Google APIs.
This design guide is shared here to inform outside developers and to make it
easier for us all to work together.
Cloud Endpoints developers may find this
guide particularly useful when designing gRPC APIs, and we strongly recommend
such developers use these design principles. However,
we don't mandate its use. You can use Cloud
Endpoints and gRPC without following the guide.
This guide applies to both REST APIs and RPC APIs, with specific focus on gRPC
APIs. gRPC APIs use Protocol Buffers to define their API surface
and API Service Configuration to configure their API services, including
HTTP mapping, logging, and monitoring. HTTP mapping features are used by Google
APIs and Cloud Endpoints gRPC APIs for JSON/HTTP to Protocol Buffers/RPC
transcoding.
This guide is a living document and additions to it will be made
over time as new style and design patterns are adopted and approved. In that
spirit, it is never going to be complete and there will always be ample
room for the art and craft of API design.
Conventions Used in This Guide
The requirement level keywords "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" used in this document are to be interpreted as described in
RFC 2119.
In this document, such keywords are highlighted using bold font.
Sections
Resource-oriented Design
For information about implementing resource-oriented design for
RPC and REST APIs, see AIP-121.
Resource Names
For information about resource names,
see AIP-122.
Standard Methods
For general information about methods, see AIP-130.
For information about standard methods, see the following AIPs:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 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)"]]
