소개
본 문서는 네트워크 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을 참고하세요.
리소스 이름
리소스 이름에 관한 자세한 내용은 AIP-122를 참고하세요.
표준 메서드
메서드에 관한 일반적인 내용은 AIP-130을 참고하세요.
표준 방법에 대한 자세한 내용은 다음 AIP를 참고하세요.
Get의 경우 AIP-131을 참고하세요.List의 경우 AIP-132를 참고하세요.Create의 경우 AIP-133을 참고하세요.Update의 경우 AIP-134를 참고하세요.Delete의 경우 AIP-135를 참고하세요.
커스텀 메서드
맞춤 메서드에 관한 자세한 내용은 AIP-136을 참고하세요.
추가 주제
다음 주제에 관한 자세한 내용은 관련 AIP를 참고하세요.
- 표준 필드는 AIP-148을 참고하세요.
- 오류는 AIP-193을 참고하세요.
- 디자인 패턴은 디자인 패턴에 관한 AIP 가이드를 참고하세요.
- 인라인 API 문서는 AIP-192를 참고하세요.
- proto3 사용에 관한 자세한 내용은 AIP-191의 문법 섹션을 참고하세요.
- 버전 관리는 AIP-185를 참고하세요.
- 이전 버전과의 호환성에 관한 자세한 내용은 AIP-180을 참고하세요.
- 파일 구조는 AIP-191의 파일 레이아웃 섹션을 참고하세요.
- 용어의 용어집은 AIP-9를 참고하세요.
다음 주제에 관한 자세한 내용은 이 가이드의 관련 페이지를 참고하세요.