Restful API设计规范

定义  

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.youkuaiyun.com/qq_37257657/article/details/81206520》

《https://www.cnblogs.com/haiyan123/p/8419972.html》