请不要再管它们叫 REST API 了

阅读数:2 2019 年 12 月 20 日 17:44

请不要再管它们叫REST API了

2000 年初,Douglas Crockford 宣称 JavaScript 是世界上被误解得最深的一门编程语言。造成误解的主要原因是糟糕的命名方式、设计上的错误和不严格的标准,等等。所以说,导致这种误解是很自然的。

去年,我在推特上发了一条有关 REST 架构范式的推文。

请不要再管它们叫REST API了

大多数人认为基于 URL 和 HTTP 动词设计的 API 就是 REST API,但这样的想法实际上错得离谱。

这个误解存在了很长一段时间。与 JavaScript 不一样的是,REST 指南已经说得很清楚了,REST 这个名词强调了状态转换(State Transfer),但大多数所谓的 REST API 设计者却忽略了这一点。

如果你问一下身边的程序员他们设计的 API 是否支持 HATEOAS,他们十有八九会瞪大了眼睛看着你,然后说:你到底在说什么?

然而,REST 的名字本身就说明了一切。它并没有说要使用哪一种协议,也没有说使用哪一种方式来标识资源,它只说到表示性状态转移(REpresentational State Transfer)。Roy Fielding 博士说,状态转移管理是 REST API 的一个必要条件。

真正的 REST API 应该为客户端提供状态以及在状态之间进行切换的方式。它提供了资源的表示(不一定是 JSON 格式)和指向相关资源的链接(超链接),这些链接可以让应用程序从一个状态切换到另一个状态。如下例所示:

复制代码
{
"id": 463219,
"firstName": "John",
"lastName": "Smith",
"company": "Acme Inc.",
"salary": 72500,
"links": [
{
"href": "https://api.myapp.com/employees/employee/463219",
"rel": "self"
},
{
"href": "https://api.myapp.com/companies/company/375",
"rel": "company"
},
{
"href": "https://api.myapp.com/payments/employee/463219",
"rel": "payments"
}
]
}

这个例子提供了资源的描述和其他相关资源的信息。

需要特别提到的是,是否使用 HTTP 协议并不重要。REST 的关键之处在于让服务器端来负责客户端的状态转移。客户端的状态几乎是由服务器端来驱动的,所以,讨论 API 版本管理并没有多大意义。客户端只要知道 REST API 的入口点就可以了,剩下的根据服务器端的响应来做决定,但这一点却被大多数人忽略了。

只是简单地将 CRUD 操作映射到 HTTP 动词的 API 与应用程序状态转移丝毫扯不上关系,你可以把它们叫作 Web API 或 HTTP API,但请不要把它们叫作 REST API。

延展阅读

我们为什么从 REST 转向 gRPC

英文原文

Please, Don’t Call Them RESTful

评论

发布