• 介绍
  • 本文档的约定

    介绍

    这是一份网络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中有详细描述,在文档中这些关键词使用粗体显示。