你真的了解restful api吗？

在以前，一个网站的完成总是“all in one”，页面，数据，渲染全部在服务端完成，这样做的最大的弊端是后期维护，扩展极其痛苦，开发人员必须同时具备前后端知识。于是慢慢的后来兴起了 前后端分离 的思想： 后端负责 数据编造 ,而前端则负责 数据渲染 ，前端静态页面调用指定api获取到有固定格式的数据，再将数据展示出来，这样呈现给用户的就是一个”动态“的过程，而关于api这部分的设计则成了一个问题。如何设计出一个便于理解，容易使用的api则成了一个问题。 而所谓的 restful 就是用来规范我们的api的一种约束。

介绍

rest 是 REpresentational State Transfer 三个单词的缩写，由Roy Fielding于2000年论文中提出，它代表着分布式服务的架构风格。而如果想你的api被称为restful api，只要遵循其规定的约束即可。

rest设计原则

资源

uri规范

资源的描述构成了uri，它一般有以下约束：

1. 使用名词。如 user, student, class api.example.com/class-manag… api.example.com/device-mana… api.example.com/user-manage… api.example.com/user-manage…

2. http method对应不同的请求动作（数据库或者业务逻辑） GET ：查询操作： HTTP GET /devices?startIndex=0&size=20 HTTP GET /configurations?startIndex=0&size=20 HTTP GET /devices/{id}/configurations HTTP GET /devices/{id} POST ：新增操作： HTTP POST /device PUT 更新操作（代表更新一个实体的所有属性） HTTP PUT /devices/{id} PATCH 部分更新（代表更新一个尸体的部分属性）由于有的浏览器兼容性问题，一般推荐使用put HTTP PATCH /devices/{id} DELETE 删除操作 HTTP DELETE /devices/{id}

3. 使用连字符（ - ）而不是（_）来提高URI的可读性 api.example.com/inventory-m… //更易读 api.example.com/inventory_m… //更容易出错

4. 在URI中使用小写字母 api.example.org/my-folder/m…

5. 不要使用文件扩展名 文件扩展名看起来很糟糕，不会增加任何优势。删除它们也会减少URI的长度。没理由保留它们。 api.example.com/device-mana… / 不要使用它 / api.example.com/device-mana… / *这是正确的URI * /

6. 使用查询组件过滤URI集合 很多时候，我们会遇到需要根据某些特定资源属性对需要排序，过滤或限制的资源集合的要求。为此，请不要创建新的API - 而是在资源集合API中启用排序，过滤和分页功能，并将输入参数作为查询参数传递。例如 api.example.com/device-mana… api.example.com/device-mana… api.example.com/device-mana… api.example.com/device-mana…

7. 不要在末尾使用 / 作为URI路径中的最后一个字符，正斜杠（/）不会添加语义值，并可能导致混淆。最好完全放弃它们。

8. 使用http状态码定义api执行结果 1xx：信息 通信传输协议级信息。

2xx：成功表示客户端的请求已成功接受。

3xx：重定向表示客户端必须执行一些其他操作才能完成其请求。

4xx：客户端错误此类错误状态代码指向客户端。

5xx：服务器错误服务器负责这些错误状态代码。 另外完整的更为详细的状态码此处不做赘述。一般简化版本的api会使用200，400，500，其中400代表客户端调用有误，将错误信息放入response：

{
  "error": "username.or.password.error"
}
复制代码

9. api版本定义 当我们需要对现有的api接口升级的时候，因为该api接口已经投入使用，所以新添加的业务可能无法保证兼容原来的逻辑，这个时候就需要新的接口，而这个接口一般表示对原来的接口的升级（不同版本），那版本怎么定义呢？

• URI版本控制（推荐）api.example.com/v1 apiv1.example.com
• 使用自定义请求标头进行版本控制 Accept-version：v1 Accept-version：v2
• 使用Accept header 进行版本控制 Accept:application / vnd.example.v1 + json Accept:application / vnd.example + json; version = 1.0

无状态

使REST API无状态有一些非常显着的优点：

1. 无状态通过将API部署到多个服务器，有助于将API扩展到数百万并发用户。任何服务器都可以处理任何请求，因为没有与会话相关的依赖。（集群）
2. 无状态使得REST API不那么复杂 - 可以删除所有服务器端状态同步逻辑。（删除session，清理多余空间）
3. 无状态API也很容易缓存。特定软件可以通过查看该一个请求来决定是否缓存HTTP请求的结果。从先前的请求中获得的状态可能会影响这个请求的可缓存性，这并不存在任何不确定性。它提高了应用程序的性能。
4. 服务器永远不会忘记每个客户端身份”，因为客户端会在每个请求中发送所有必要的信息。（携带token）

那么无状态又要怎么实现呢？前面我们已经说了，服务端不应该再保存session会话，这个工作全部交由http请求去标识，而最常见的做法则是使用token。生成token可以考虑使用jwt，oauth。其中jwt可以参考我的另一篇文章： www.jianshu.com/p/6ff0e30fc…

总结

我们首先介绍rest服务背景，引出rest架构的介绍，最后重点介绍了rest api的约束设计。

关注我，这里只有干货！