본 문서는 네트워크 API를 위한 종합 디자인 가이드입니다. 2014년부터 Google 내부에서 사용되었으며, Cloud APIs 및 기타 Google APIs를 디자인할 때 Google에서 따르고 있는 가이드입니다. 이러한 디자인 가이드를 여기에서 공유하는 이유는 외부 개발자에게 정보를 제공하는 동시에 모두가 더욱 쉽게 협력할 수 있도록 하기 위함입니다.
Cloud Endpoints 개발자라면 gRPC API를 디자인할 때 이 가이드가 얼마나 유용한지 알 수 있습니다. 따라서 이러한 개발자들은 이 디자인 원칙을 사용하는 것이 좋습니다. 하지만 본 가이드를 의무적으로 사용해야 하는 것은 아닙니다. 가이드를 따르지 않고 Cloud Endpoints 및 gRPC를 사용해도 좋습니다.
이 가이드는 REST API와 RPC API 모두에 적용되지만 특히 gRPC API를 중심으로 설명합니다. gRPC API는 프로토콜 버퍼를 사용하여 API 표면을 정의하고 API 서비스 구성을 사용하여 HTTP 매핑, 로깅, 모니터링이 포함된 API 서비스를 구성합니다. HTTP 매핑 기능은 Google API와 Cloud Endpoints gRPC API에서 JSON/HTTP부터 프로토콜 버퍼/RPC 트랜스코딩에 이르기까지 사용됩니다.
본 가이드는 현재 사용되는 문서이지만 앞으로 시간이 지나면서 새로운 스타일과 디자인 패턴이 도입 및 승인을 거쳐 추가될 예정입니다. 이러한 태도를 견지하면서 앞으로도 완전하지 않고 항상 API 디자인을 개선할 수 있는 가능성을 충분히 남겨놓을 것입니다.
이 가이드에서 사용되는 규칙
요구 사항의 수준을 나타내는 키워드로서 본 문서에서 사용되고 있는 '해야 합니다', '안 됩니다', '필요합니다', '해야 합니다', '안 됩니다', '해야 합니다', '안 됩니다', '권장됩니다', '할 수 있습니다', '선택 사항입니다'는 RFC 2119의 설명에 따라 해석됩니다.
이번 문서에서 이러한 키워드는 굵은 글꼴로 강조하여 표시됩니다.
섹션
리소스 중심 디자인
RPC 및 REST API의 리소스 중심 설계를 구현하는 방법에 관한 자세한 내용은 AIP-121을 참고하세요.
[[["이해하기 쉬움","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-08(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)"]]
