[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。那么如何简化，就需要本身去琢磨和体会了。