REST 祖师爷 Roy Fielding 说： RPC 就不适合 RESTful 风格。只有超文档适合用 REST

[lambdaq]

I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.

What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?

--Roy Fielding, Creator of the term REST

REST APIs must be hypertext-driven

https://htmx.org/essays/how-did-rest-come-to-mean-the-opposite-of-rest/

[baiyi]

虽然 HTTP 协议是基于 RESTful 风格设计的，但不是用了 HTTP 协议的 API 就能叫做 REST API 。
Fielding 一直都不承认现在的 REST API ，认为它们只能叫做 HTTP API 或是 JSON RPC ，还曾经点名过微软的 REST API 。

文章里提到的超媒体驱动是我认为现在 REST API 最难达到的一点，Github 的 REST API 是我认为最接近的，但它仍然需要文档的帮助。
在 Fielding 的理念中，难道你访问一个网页，还需要有个网页使用手册来帮助你理解吗？网页有变更，难道要通知用户去查看新的手册吗？这些都是现在 API 的问题。
在我看来，目前（好几年没关注了，认知停留在 2019 年）的 OpenAPI 或者是 JSON Schema 这些规范提供的描述性格式都不足以达到文档的效果，所以也很难去掉文档的辅助，更别提客户端动态适应 API 的修改了。

[lambdaq]

@baiyi 其实对于一个 hypertext 来说是这样的。Roy 的理念是从首页入手，所有的增删改查的操作都是可以在首页 hypertext 里找到直接的操作子级 URL 的 。就像 unix 文件系统一样，根目录 / 下可以列表，可以增加，可以删除。

感觉和他后来做的 WebDAV 就很契合。

[gam2046]

现阶段，适配 REST API 的只有 OSS 了，功能足够简单，增删改的谓语词也足够用，一切都不言自明。

其他所有和业务相关的 API ，都无法脱离文档，仅仅靠 REST 那几个谓语词根本无法确定意图。

[lambdaq]

@gam2046 OSS 这种面向「资源」的场景的确很适合 RESTful 。