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 的 POST、GET、PUT、PATCH 和 DELETE 方法。这使得要学习的内容减少了很多，因为开发人员可以专注于资源及其关系，并假定它们拥有的标准方法同样很少。

什么是 REST API？

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

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

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

Comments
Write a Comment