定义
Restful与技术无关,他是一种软件架构的风格, rest是Representational State Transfer,中文翻译为表征状态转移。Restful是以资源的角度来审视整个网络,将分布在网络各个节点的资源通过URL进行标识,客户端通近URL来获取资源的表征,获取表征之后加上相应的动词(PUT/DELETE/POST/GET/PATCH)来改变资源的表征状态。将一切数据都视为资源是REST区别其他架构风格最本质的属性。
语法
RFC 3986定义了通用的语法:
URI=scheme"://"authority"@"host":"ip"/"path["?"query]["#"fragment]
scheme:使用的协议,如http https ftp
host:服务器的IP地址或者域名
port:端口
path:访问资源的路径,就是各种web框架中定义的route路由
query:发送给服务器的参数
fragment:锚点,定义到页面的资源,锚点为资源ID
URL设计
动词+宾语
RESTful的核心思想就是客户端发出的数据操作指令是“动词+宾语”的结构,如 GET /articles这个命令 GET是动词 /articles是宾语。
动词通常就是http的五种方法,对应CRUD操作
- GET 读取
- POST 新建
- PUT 更新
- PATCH 更新(局部更新)
- DELETE 删除
动词的覆盖
有些客户端只能使用GET和POST两种http方法。可以使用POST方法来模拟(PUT/PATCH/DELETE)这三个方法。这时客户端的HTTP请求要加上X-HTTP-Method-Override属性,告诉服务端来使用哪一个动词覆盖当前的POST方法,如下例如下:
POST /api/articles/{id}
X-HTTP-Method-Override: DELETE
宾语必须是名词
宾语就是是API的URL部分,是http动词作用的对象。它应该是名词而不能是动词
复数宾词
为了统一,建议使用复数URL
避免多级URL
资源需要多级分类,很容易写出多级URL,但是这种URL不利于扩展,语义也不明确,建议除了第一级,其他级别都用查询字符串表示。如下面两个URL的比较
GET /api/authors/1/articles/10
GET /api/authors/1?articles=10
状态码
状态码必须精确
客户端每一次请求,服务端都必须给出回应,回应包括http状态码和数据两部分
http状态码是一个三位数,分成五个类别
- 1xx: 相关信息
- 2xx:操作成功
- 3xx:重定向
- 4xx:客户端错误
- 5xx:服务端错误
这五类包含了100多种状态码,覆盖了大部分可能遇到的情况,每一种状态码都有标准或约定的解释,客户端可以根据状态码就知道发生了什么情况,所以服务端已应该尽可能返回精确的状态码
状态码详情请参考这里
参考
《http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html》
《https://blog.csdn.net/qq_37257657/article/details/81206520》
《https://www.cnblogs.com/haiyan123/p/8419972.html》