Google API设计指南-面向资源的设计

翻译自 API Design Guide - Resource Oriented Design

这篇设计指南的目的是帮助开发者设计出简单、一致、易于使用的网络 API,同时它也帮助我们统一了 RPC API(基于 socket)与 REST API(基于 HTTP)的设计。

传统上,人们参考像 CORBA 和 Windows COM 这样的 API 接口和方法来设计 RPC API。随着时间推移,越来越多的接口和方法被添加。最后的结果是被数量众多的接口和方法淹没,每一个都和其他不同。为了正确使用它们开发者必须仔细学习每一个接口或方法,这必定会消耗时间并容易引入问题。

REST 架构风格最早出现于2000年,主要设计为与 HTTP/1.1 一起使用。它的主要原则是定义能够被少量方法操作的命名资源。资源和方法被认为是 API 的名词和动词。与 HTTP 协议配合,资源名自然地映射为 URL,方法自然地映射为 HTTP 方法 POSTGETPUTPATCHDELETE

HTTP REST API 在互联网领域已经取得了巨大成功。在2010年,约 74% 的网络 API 是 HTTP REST API。

虽然 HTTP REST API 在互联网特别流行,但它们承载的流量却比传统的 RPC API 要少。例如,在美国高峰时期的约一半流量是视频内容,但因为效率问题,很少有人会考虑使用 REST API 来传输这些内容。在数据中心,许多公司使用基于 socket 的 RPC API 来传输大部分网络流量,这会比 REST API 高出几个数量级。

实际上,由于种种原因 RPC API 和 HTTP REST API 都是需要的。理想情况下一个 API 平台应该为所有 API 提供最好的支持。此指南将会帮助你设计并实现符合这一原则的 API。它将面向资源的设计原则应用到一般的 API 设计中,并且定义了许多通用的设计模式来提升可用性并降低复杂性。

注意:此设计指南解释了如何在独立于编程语言、操作系统或者网络协议的 API 设计中应用 REST 原则,而不是仅用于创建 REST API 的指南

什么是 REST API?

REST API 被建模成可单独寻址的资源(API 的名词)的集合。资源通过它们的资源名来引用,通过一小组方法(也被称为动词)来操作。

REST Google API 的标准方法(也叫 REST 方法)是 List Get Create UpdateDelete。当存在类似数据库事务这种不能被简单地映射到标准方法的需求时,API 设计者也可以使用自定义方法(也叫自定义动词自定义操作)。

注意:自定义动词不表示创造自定义的 HTTP 动词来支持自定义方法。对于基于 HTTP 的API,简单地映射到最合适的 HTTP 动词即可。

设计流程

此设计指南建议采用如下步骤来设计面向资源的 API(更详细的内容请参考后面的小节)

  • 确定 API 提供的资源类型

  • 确定资源间的关系

  • 依据类型和关系来确定资源名方案

  • 确定资源结构

  • 为资源添加最少的方法集

资源

面向资源的 API 通常以资源层次进行建模,每一个节点是一个简单的资源资源集合。方便起见,通常将它们称为资源和集合。

  • 集合包含具有相同类型的资源列表。例如一个用户拥有联系人的集合

  • 资源拥有一些状态和 0 个或多个子资源。每一个子资源可以是简单资源或资源集合

例如,Gmail API 有用户的集合,每个用户有信息的集合、线程的集合、标签的集合、一个资料资源和一些设置项资源。

虽然存储系统和 REST API 之间存在一些概念上的一致性,但是具有面向资源的 API 的服务不一定是数据库,并且在解释资源和方法方面具有巨大的灵活性。例如,创建日历事件(资源)可以为参加会议者创建附加事件,向参加者发送邮件邀请,预约会议室和更新视频会议时间表。

方法

面向资源的 API 的关键特性是它通过对资源执行的方法(功能)来强调资源(数据模型)。一个典型的面向资源的 API 通过少量方法暴露大量资源。这些方法可以是标准方法也可以是自定义方法。对于本指南,标准方法是 List Get Create UpdateDelete

当一个 API 功能自然地映射到一个标准方法时,应该(should) 在API 设计中使用此方法。对于不能自然映射到标准方法的功能,可以(may) 使用自定义方法自定义方法提供了与传统 RPC API 相同的设计自由度,能够用来实现常见的编程模式,例如数据库事务和数据分析。

例子

下面的部分列出了一些实际的例子,展示了如何将面向资源的 API 设计应用到大规模服务上。

Gmail API

Gmail API 服务实现了 Gmail API 并提供了 Gmail 的大部分功能。它有以下资源模型:

  • Gmail API 服务:gmail.googleapis.com

  • 用户集合:users/*。每个用户有以下资源

    • 消息集合:users/*/messages/*

    • 线程集合:users/*/threads/*

    • 标签集合:users/*/labels/*

    • 修改历史集合:users/*/history/*

    • 代表用户资料的资源:users/*/profile

    • 代表用户设置项的资源:users/*/settings

Google Cloud Pub/Sub API

pubsub.googleapis.com 服务实现了Google Cloud Pub/Sub API,它定义了下面的资源模型:

  • API 服务:pubsub.googleapis.com

  • 话题集合:projects/*/topics/*

  • 订阅集合:projects/*/subscriptions/*

注意:其他 Pub/Sub API 的实现可能会选择不同的资源名称方案

查看其他章节

1.2k 声望
33 粉丝
0 条评论
推荐阅读
Google API 设计指南-词汇表
翻译自 API Design Guide - Glossary 网络 API(Networked APIs) 通过计算机网络中运行的应用程序接口。它们使用包括 HTTP 在内的网络协议进行通信,并且生产和消费 API 的往往是不同的组织。 Google API Google...

tailnode1阅读 2.2k

给新人推荐这 6 款 API 测试工具
Postman: Postman 是一个流行的 API 开发和测试工具,提供了丰富的功能,包括请求构建、测试自动化、数据驱动等。用户可以通过 Postman 的界面轻松创建和测试 RESTful API。

圆圆大姐头3阅读 431评论 1

就这些了, 常见 6 款API 文档工具推荐
Swagger: Swagger 是一个开源的 API 文档管理工具,可以通过注解自动生成 API 文档,并提供交互式 UI 和 API 调试功能。 Swagger 支持多种语言和格式,包括 Java、Python、JSON、YAML 等。

圆圆大姐头3阅读 331

马斯克都不懂的 GraphQL,API 网关又能对其如何理解?
上个月马斯克评论 Twitter App 滥用 RPC 后,与一些 Twitter 的技术主管发生了矛盾 —— 直言马斯克不懂技术。那这个马斯克都不懂的 GraphQL 到底是什么?

API7_技术团队1阅读 1.1k

搞懂 API ,地图 API 制作方法分享
选择地图 API 平台:目前市场上有很多地图 API 平台供选择,比如 Google Maps API、百度地图 API、高德地图 API 等,需要根据实际需求选择合适的平台。

圆圆大姐头2阅读 291

最强 Mock 工具,没人反对吧?
在开发过程中,由于后端与前端并行开发,或者前端需要等待后台开发,难以保证对接效率,同时即使用开发好的 API 对接,也有可能一个 API 不通就阻塞了整个软件的对接工作。同时对软件的敏感度也很高,一不小心就...

圆圆大姐头2阅读 187

我总结了一次, API 接口设计原则有这些
结合我多年在 API 行业摸爬滚打的经验,我总结了一下,API 接口设计原则有这几条:接口设计应该简单易用,易于理解和使用;接口设计应该支持多种格式,如JSON、XML等;接口设计应该支持多种请求方式,如GET、POST...

圆圆大姐头1阅读 249

1.2k 声望
33 粉丝
宣传栏