什么是 RESTful API

简要定义

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
    }
}