你真的了解restful api吗？

时间 2019-12-01

标签了解 restful api 繁體版

原文原文链接

前言

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

介绍

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

rest设计原则

客户端-服务器：经过将用户UI与数据存储分开，咱们能够简化服务器组件来提升跨多个平台的用户界面的可移植性并提升可伸缩性。它能够比表现成先后端分离的思想。
无状态：从客户端到服务器的每一个请求都必须包含理解请求所需的全部信息，而且不能利用服务器上任何存储的上下文。这表示你应该尽量的避免使用session，由客户端本身标识会话状态。（token）
规范接口：REST接口约束定义：资源识别; 请求动做; 响应信息; 它表示经过uri标出你要操做的资源，经过请求动做（http method）标识要执行的操做，经过返回的状态码来表示此次请求的执行结果。
可缓存：缓存约束要求将对请求的响应中的数据隐式或显式标记为可缓存或不可缓存。若是响应是可缓存的，则客户端缓存有权重用该响应数据以用于之后的等效请求。它表示get请求响应头中应该表示有是否可缓存的头（Cache-Control) 其中1，2，3约束最为重要，其中1容易理解。接下来咱们就谈谈无状态和规范接口的原则。

uri规范

资源的描述构成了uri，它通常有如下约束：json

使用名词。如 user, student, class

api.example.com/class-manag…后端

api.example.com/device-mana…api

api.example.com/user-manage…浏览器

api.example.com/user-manage…缓存

使用http method来对应不一样的请求动做（数据库或者业务逻辑） GET：查询操做：

HTTP GET /devices?startIndex=0&size=20 表示按照查询条件获取设备列表服务器

HTTP GET /configurations?startIndex=0&size=20restful

HTTP GET /devices/{id}/configurationssession

HTTP GET /devices/{id}

POST：新增操做：

HTTP POST /device 表示新增一个设备 PUT 更新操做（表明更新一个实体的全部属性）

HTTP PUT /devices/{id} 表示更新一个设备（设备惟一id区分） PATCH 部分更新（表明更新一个实体的部分属性）因为有的浏览器兼容性问题，通常推荐使用put

HTTP PATCH /devices/{id} 表示更新device的部分属性

DELETE 删除操做 HTTP DELETE /devices/{id} 表示删除一个设备，根据id区分

使用连字符（ - ）而不是（_）来提升URI的可读性

api.example.com/inventory-m… //更易读

api.example.com/inventory_m… //更容易出错

在URI中使用小写字母(特殊状况除外，例如专有名词) api.example.org/my-folder/m…
不要使用文件扩展名文件扩展名看起来很糟糕，不会增长任何优点。删除它们也会减小URI的长度。没理由保留它们

api.example.com/device-mana… / 不要使用它 /

api.example.com/device-mana… / *这是正确的URI * /
使用查询组件过滤URI集合

不少时候，咱们会遇到须要根据某些特定资源属性对须要排序，过滤或限制的资源集合的要求。为此，请不要建立新的API - 而是在资源集合API中启用排序，过滤和分页功能，并将输入参数做为查询参数传递。例如

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
复制代码

不要在末尾使用/

做为URI路径中的最后一个字符，正斜杠（/）不会添加语义值，并可能致使混淆。最好彻底放弃它们。

使用http状态码定义api执行结果

1xx：信息 通讯传输协议级信息。

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

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

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

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

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

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无状态有一些很是显着的优势：

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

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

总结

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

关注我，这里只有干货！