[01] 浅谈RESTful风格的API
标签：htm .com 客户 log amp 参考 nbsp article stat
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、参考链接
- REST与RESTFul API最佳实践
- 理解RESTful架构
- RESTful API 设计指南
- 我所认为的RESTful API最佳实践
[01] 浅谈RESTful风格的API
标签：htm .com 客户 log amp 参考 nbsp article stat
原文地址：https://www.cnblogs.com/deng-cc/p/8331465.html
评论