[01] 浅谈RESTful风格的API

1、什么是RESTful风格的API

REST，即Representational State Transfer，可以理解为“（资源的）表现层状态转化”。

在网络上，我们通过浏览器输入url，来访问和获取到所需要的资源。这里的url，是对资源位置的定位描述，其实也是一种资源的具体呈现的方式，即这里所说的“表现层”。我们访问资源的过程涉及到数据和状态的变化，“建立在表现层（url）基础上使资源状态发生变化”，也即“表现层状态转化（REST）”了。

符合REST规范的API，则称之为RESTful风格的API，再大白话一点，能让我们“通过API接口名称就能明白它的作用”，它优雅、规范、易懂，省去了许多无意义的沟通和文档。核心规范是什么呢？使用HTTP协议中的四种不同请求方式，来代表四种不同的动词操作：GET用来获取资源；POST用来新建资源；PUT用来更新资源；DELETE用来删除资源。

具体一点来说，RESTful API有如下特点：

基于“资源”，数据也好，服务也好，在RESTful设计中一切都是资源
每个URL表示一种资源
URL语义清晰明确，不出现动词，只有名词（操作的动词是通过请求方式来表示）
使用HTTP的 POST、DELETE、PUT、GET 来表示对资源的增删改查
尽量使用JSON而不是XML
应该将API的版本号放入URL

举例来说，某API提供动物园（zoo）系统相关信息，则RESTful的API风格如下：

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

再具体一点：

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

API同时也可以提供一些参数，用来过滤返回结果，常见参数如下：

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

再来一个鲜活的例子，豆瓣图书相关的开发API：

先看看这个链接，是什么作用？再试试直接访问（GET方式），返回的内容是什么？https://api.douban.com/v2/book/1220563

2、RESTful什么时候好用

对于开放的API，豆瓣、新浪微博、GitHub，好用，非常合适；对于内部开发，不好用。

基于资源型的RESTful API 接口粒度和返回结果过于的“粗”，它通常返回的都是完整的数据模型，这对于客户端非常不友好。但开放API之所以开放，就是因为它不知道你到底需要什么返回结果，既然不知道，那么我干脆都返回给你。这样的好处是通用，但客户端不好处理。你只需要一个字段，服务器却丢给你十几个，作为客户端开发者你怎么想？

内部开发由于需求非常明确，通常来说服务器是不应该简单粗暴的直接甩资源实体给客户端的。那RESTful API就不能接入到内部开发吗？当然不是，我们需要灵活一些借鉴RESTFul中的优点，来设计我们的内部API。那么如何简化，就需要自己去琢磨和体会了。

3、参考链接