RESTful API学习

RESTful是目前最流行的API设计规范，用于web数据接口的设计。REST(Representational State Transfer，表示层状态转移)，看了翻译还是懵逼。

表示层用来表示什么东西？

其实这个表述的主体是网络中的资源。它通常用URI(Uniform Resource Identifier)标识，如果缺少这个标识，网络中其他人就找不到，也就称不上资源了。这个体现在HTTP请求头信息中，用Request URL字段指定。

表示层又是什么东东？

既然表示的主体是网络中的"资源",那么表现层就是用来呈现资源的形式。比如网络中的一个文本资源，它可以用txt格式表现，也可以用html格式，xml格式等等。
那上面说用URI标识资源，那么为什么还用表示层呢？原因在于URI代表的是一个真实的实体，没能表现它的形式。
表示层体现在HTTP请求的头信息中，用Accept和Content-Type字段指定。其中客户端通过Accept来请求一种特定格式的表现，服务端通过Content-Type告诉客户端资源的表现形式。

这个状态转移又是什么情况？

网上有好多种说法，各有各的道理。我认为"资源表示层的状态转移"，可以从两方面来理解：一是转移作为动词；二是作为名词。作为动词，即指资源转移的某种形式，例如采用什么样的方式来转移资源，这个体现在HTTP请求头信息中，用Request Method字段指定；作为名词，即指资源的一种转移状态，例如：301表示资源已经被永久转移到其他URL。这个体现在HTTP请求的响应头中，用Status Code字段表示。

设计注意规范

将上面三部分内容结合起来，我们就可以得出RESTful API的一些基本设计规范：
1.既然用URI表示一个资源实体，那么它就应该是个名词，所以URI中不应该有动词。例如获取文本资源。

https://blog.csdn.net/benben_2015/article      正确的
https://blog.csdn.net/benben_2015/getArticle   错误的

错误的URI中含有get动词，如果想表示这个get动作，可以在HTTP请求的Request Method中指定。

https://blog.csdn.net/benben_2015/article        正确的
https://blog.csdn.net/benben_2015/v1/article   错误的

这个错误的原因在于在URI中加入了版本号v1，版本号并不是用来表示资源的，所以URI中不需要。如果想表示版本号，可以在HTTP请求头信息的Accept字段中进行区分，例如：

Accept:vnd.example-com.foo+json; version=1.0

2.由于资源的分类，所以有可能会出现多级URI。这样是不利于URI的扩展的，语义也不明确。这个我们可以通过查询字符串表示。

https://blog.csdn.net/benben_2015/article/categories/2  不推荐
https://blog.csdn.net/benben_2015/article?categories=2  推荐

3.状态码必须精确，比如301表示永久重定向，302表示暂时重定向。如果你在应该使用301的时候使用了302，那么你每次请求，内容都不会被缓存或保存。

参考文章

1. RESTful API最佳实践