소개
본 문서는 네트워크 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의 설명에 따라 해석됩니다.
이번 문서에서 이러한 키워드는 굵은 글꼴로 강조하여 표시됩니다.