Este é um guia geral de criação de APIs em rede que é usado no Google desde 2014 para desenvolver as APIs do Cloud e outras APIs do Google. Compartilhamos este guia para instruir os desenvolvedores externos e facilitar o trabalho em conjunto.
Os des envolvedores do Cloud Endpointsm podem achar este guia particularmente útil ao projetar APIs de gRPC, e é altamente recomendável que esses desenvolvedores usem esses princípios de design. No entanto, não obrigamos o uso. Você pode usar o Cloud Endpoints e o gRPC sem seguir o guia.
Este guia aplica-se tanto às APIs REST quanto às APIs RPC, com foco específico nas APIs
gRPC. As APIs gRPC usam buffers de protocolo para definir a superfície da API
e aplicam a configuração de serviço da API para configurar os serviços, incluindo
mapeamento HTTP, geração de registros e monitoramento. Os recursos de mapeamento HTTP são usados pelas APIs do Google
e pelas APIs gRPC do Cloud Endpoints para JSON/HTTP para a
transcodificação de RPC/buffers de protocolo.
Este guia é um documento em construção, e mais adições serão feitas ao longo do tempo conforme novos estilos e padrões de projeto forem adotados e aprovados. Considerando isso, ele nunca será completo e sempre haverá um amplo espaço para a arte e a construção de projetos da API.
Convenções usadas neste guia
As palavras-chave de nível de exigência "PRECISA", "NÃO PODE", "OBRIGATÓRIO", "DEVERÁ", "NÃO DEVERÁ", "DEVE", "NÃO DEVE", "RECOMENDADO", "PODE" e "OPCIONAL" usadas neste documento serão interpretadas conforme descrito na RFC 2119.
Neste documento, essas palavras-chave são destacadas usando a fonte em negrito.
Seções
Design voltado para recursos
Para informações sobre como implementar o design orientado a recursos para APIs RPC e REST, consulte AIP-121.
Nomes dos recursos
Para mais informações sobre nomes de recursos, consulte AIP-122.
métodos padrão
Para informações gerais sobre métodos, consulte AIP-130.
Para informações sobre métodos padrão, consulte as seguintes AIPs:
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 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)"]]
