介绍

这是一份网络API的通用设计指南。Google内部从2014年开始使用它，我们在设计Cloud API和Google API时也遵从了这份指南。我们把它分享给Google以外的开发人员，这也会让我们的合作变得更顺利。

外部开发者可能会发现在设计使用Google Cloud Endpoint(译者注：GCE，面向开发者的api管理平台)的API时这份指南非常有用，我们强烈建议外部开发者使用这些设计准则。尽管如此，我们并不强求任何非Google的开发人员使用这份指南，你可以在使用Cloud Endpoint或者gRPC时不遵从这份指南。

这份指南既适用于REST API也适用于RPC API，并重点关注gRPC API。gRPC API使用Protocol Buffer定义API接口，并使用API Service Configuration去配置API服务，包括HTTP映射，日志和监控。Google API和gRPC Cloud Endpoint API使用HTTP映射特性用把JSON/HTTP转码到Protocal Buffer和RPC。

这份指南会随着时间的变化持续更新，去采用和适应新风格和设计模式。本着这个原则，这份指南从来不会处于完备状态，API的设计艺术和技艺总是有提升的空间。

本文档的约定

本文档所用的需求级别描述词语”MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”在RFC 2119中有详细描述，在文档中这些关键词使用粗体显示。