简要定义

RESTful 设计风格，简而言之，就是用 HTTP method 表示操作，URL 表示被操作的资源的一种 HTTP API 设计风格。

这其中，GET 表示获取（查询），POST 表示创建，PUT 表示修改，DELETE 表示删除。

为什么将 API 设计成 RESTful 风格

清晰，标准，简明，扩展方便，可维护性好。

拆解

REST，（Resource）Representational State Transfer，即“（资源的）表现层状态转移”。

我们上网（通过浏览器）或通过 HTTP Client 和服务器交互，都是在操作服务器上的资源（resource）。

但资源我们很难直接操作，也不安全。例如，我们不大可能直接去服务器的数据库改数据，也不大可能去服务器的存储中改文件，而是经过一个表现层（JSON、XML 等）并通过 HTTP 动词来操作。

HTTP 动词表示动作；URL 定位到资源（这意味着，URL 一般只出现名词）；请求体（request body）和响应体（response body）以某种格式表现资源。

这就是 REST 的大致含义。

REST 的一般最佳实践

URL

全用小写字母，用横线（-）分隔，通常只出现名词。

正例：

修改某个作者下的某个文章

PUT /api/author/3/article/33112

查看某项目下的流水线列表，第 1 页，每页 30 个

GET /api/project/<project_id>/pipelines?page_size=30&page_no=1

反例：

@RequestMapping("/getTotalElectricityForIntervalDays")

直接把函数名一抄，既未明确 method，又不是 REST 风格。

method

动词按照语义对应到操作。GET 查，POST 增，DELETE 删，PUT 和 PATCH 改。

HEAD、GET 须安全、幂等、无副作用。所以，GET 用来表示纯读操作，不应使用 GET 表示增、删、改。

PUT、PATCH 须幂等。而 PUT 和 PATCH 的区别是，PUT 表示修改一个资源的整体，PATCH 表示修改一个资源的部分字段。

如果 method 无法表达出相应的动作，则 method 用 POST，动作可以在 URL 中体现，例如：

POST /api/foo/3/bar/_search

这里的动作前面加了下划线，因为 search 不是资源，所以特殊化处理。

如果某个动作在软件中使用非常频繁，可以考虑自定义 method。

HTTP header

正确使用状态码，发挥其本身的含义，而不是一股脑使用 200、400、500。

例如：

200 表示一般成功；

201 表示已创建；

202 表示接受了某个命令（异步执行）；

419 表示触发了限流；

……

HTTP body

response body 收到即用，无需拆箱。描述性的信息放在 header。

正例：

header

X-Code: 0
X-Message: ok

body

{
    "foo": "qwer",
    "bar": 33
}

反例：

{
    "code": 0,
    "message": "ok",
    "data": {
        "foo": "qwer",
        "bar": 33
    }
}