api

简介

最近在写一个API设计的规范文档或者指南,参考了一些网上的文章和业内其他公司的设计,其中最让我感到受益匪浅的是Google的API 设计指南,其中有很多点是我之前做设计比较疑惑的地方,这里整理一篇博客,作为自己思考的沉淀。微软的更偏向与Web API设计,并没有参考太多,文中对比REST API设计的时候,会提到一些。

  • Google API 设计指南 https://cloud.google.com/apis/design

    • 这是联网 API 的通用设计指南。它自 2014 年起在 Google 内部使用,是 Google 在设计 Cloud API 和其他 Google API 时遵循的指南。我们在此公开此设计指南,目的是为外部开发者提供信息,使我们所有人能更轻松地协同工作。
  • 微软 Web API 设计 https://docs.microsoft.com/zh-cn/azure/architecture/best-practices/api-design

    • 大多数新式 Web 应用程序都会公开 API,客户端可以使用这些 API 来与该应用程序交互。 设计良好的 Web API 应旨在支持:
    • 平台的独立性。 不管 API 的内部实现方式如何,任何客户端都应该能够调用该 API。 这就需要使用标准协议并创建一种机制,使客户端和 Web 服务能够就交换数据的格式达成一致。

    • 服务演变。 Web API 应能在不影响客户端应用程序的情况下改进和添加功能。 随着 API 的发展,现有客户端应用程序应可继续运行而无需进行任何修改。 所有功能应该是可发现的,使客户端应用程序能够充分利用它。

    本指南阐述在设计 Web API 时应考虑的问题。

基于资源的设计

在Google和微软的指南中,第一点都指向了基于资源设计这个原则。在REST之前(或者现在),大家都在使用SOA或者RPC方式来设计API,常见的Web API大概如下

// 只有GET和POST方法,命名凭感觉
GET /getOrderList
GET /getMyOrder
POST /getOrderProductInfo.action
POST /isShowReminderBtns.action
POST /findOrdersHaveDetailsNew.action
POST /app/del

//或者。。。
POST /order?method=order_add&params={"total_price":1000,"sku_id":10011}
GET  /order?method=order_by_order_id_get&params={"orderId":xxx}
POST /order?method=order_pay_state_update&params={orderId:'xxx',loanPrice:100}

RPC API 通常根据接口和方法设计。随着时间的推移,接口和方法越来越多,最终结果可能是形成一个庞大而混乱的 API 接口,因为开发者必须单独学习每种方法。显然,这既耗时又容易出错。

引入 REST 架构风格主要是为了与 HTTP/1.1 配合使用,但也有助于解决这个问题。其核心原则是定义可以用少量方法控制的命名资源。资源和方法被称为 API 的“名词”和“动词”。使用 HTTP 协议时,资源名称自然映射到网址,方法自然映射到 HTTP 的 POSTGETPUTPATCHDELETE 方法。这使得要学习的内容减少了很多,因为开发人员可以专注于资源及其关系,并假定它们拥有的标准方法同样很少。

什么是 REST API?

REST API 是可单独寻址的“资源”(API 中的“名词”)的“集合”。资源通过资源名称被引用,并通过一组“方法”(也称为“动词”或“操作”)进行控制。

REST Google API 的标准方法(也称为“REST 方法”)包括 ListGetCreateUpdateDelete。API 设计者还可以使用“自定义方法”(也称为“自定义动词”或“自定义操作”)来实现无法轻易映射到标准方法的功能(例如数据库事务)。

注意:自定义动词并不意味着创建自定义 HTTP 动词来支持自定义方法。对基于 HTTP 的 API 而言,它们只是映射到最合适的 HTTP 动词。

Comments
Write a Comment