通俗讲解 RESTful (2)

举个例子，用户 X 的手机话费余额为 2 元，他用支付宝给手机充了 100 元话费，如果将这个操作描述为“给 X 的账户余额增加 100 元”那就是非幂等的，重复操作几次运营商就亏大了。但是，如果将这个操作描述为“将 X 的账户余额设置为 102 元”，那这个操作就是幂等的。简单来说：

幂等操作：将账户 X 的余额设置为 102 元；

非幂等操作：将账户 X 的余额增加 100 元。

注意：这里的幂等性的例子并不严谨，本文主要不是讲幂等性的，所以只是举个简单的例子，不做深入探讨。

3 RESTful 的其他细节 3.1 命名规则

（1）全部小写，用 _ 或 - 线连接。

例如我在上面给出的例子 ：

https://api.example.com/add_user

之所以不用驼峰命名法，是因为早期的 URI 一般都是表示服务器上的文件路径，而不同服务器对大小写的敏感性是不同的，为了兼容不同服务器所以才规定不能混用大小写字母。

（2）URL 中只用名词指定资源，因为 REST 的核心是资源，而表示资源的词语天然就是名词。

（3）资源用复数表示。

3.2 版本

一种方法是在 URL 中添加版本号，例如：

https://api.example.com/v1/users

另一种方法是将版本号加在 HTTP 请求头信息的 Accept 字段中，例如：

Accept: version=1.0

虽然有很多博客里推荐里说是推荐在 header 里添加版本信息，因为不同的版本表示的资源依然是同一个，所以不应该用不同的 URL。但是以我目前了解到的情况来看，绝大多数公司都是将版本号放在 URL 中的，并且推荐这么做，简单直观。

网上能找到的版本号加在 URL 中的例子，都是如我上例所示的写法。但是 Jack_Zeng 指出，这样写容易有歧义，会让人误以为 v1 也是资源的一部分，一般都是这么写：

https://api.example.com/users?api-version=1
3.3 HTTP 状态码

知乎上另一大神对 RESTful 的解释，相比于 Ivony 多了一句话，他用了三句话来描述：

看 Url 就知道要什么

看 http method 就知道干什么

看 http status code 就知道结果如何

前两句和 Ivony 的是一个意思。这第三句我觉得总结得也很经典。

http 状态码有 100 多种，我们并不需要全部用到，只需要了解其中常用的就可以了

200 – OK – 一切正常

201 – OK – 新资源已经被创建

204 – OK – 资源删除成功

304 – 没有变化，客户端可以使用缓存数据

400 – Bad Request – 调用不合法，确切的错误应该在 error payload 中描述

401 – 未认证，调用需要用户通过认证

403 – 不允许的，服务端正常解析和请求，但是调用被回绝或者不被允许

404 – 未找到，指定的资源不存在

422 – 不可指定的请求体 – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失

500 – Internal Server Error – 标准服务端错误，开发人员应该尽量避开这种错误

参考资料：

https://www.zhihu.com/question/28557115

https://blog.csdn.net/mingjia1987/article/details/79651241