Restful-API设计最佳实战--Django播客系统(五)

谁借莪１个温暖的怀抱￠ 2024-04-19 10:38 25阅读 0赞

# Restful-API设计最佳实战–Django播客系统(五) #

### 文章目录 ###

*  Restful-API设计最佳实战--Django播客系统(五)
 *   *  RESTFul
     *   *  1.协议
         *  2.HTTP方法
         *  3.使用名称
         *  4.集合功能
         *  5.状态码
         *  6.错误处理
         *  7.版本
         *  8. 返回结果

## RESTFul ##

*  REST(Representational State Transfer),表现层状态转移。
 *  它首次出现在2000年Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一。
 *  表现层是资源的表现层，对于网络中的资源就需要URI(Uniform Resource Identiﬁer)来指向。

### 1.协议 ###

*  使用HTTP或者HTTPS。对外若有安全性要求，可以使用HTTPS。但是内部服务间调用可以使用HTTP或HTTPS。

### 2.HTTP方法 ###

*  HTTP请求中的方法表示执行的**动作**

<table> 
 <thead> 
  <tr> 
   <th align="left">常用方法(动词)</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">GET</td> 
   <td align="left">获取资源</td> 
  </tr> 
  <tr> 
   <td align="left">POST</td> 
   <td align="left">创建新的资源</td> 
  </tr> 
  <tr> 
   <td align="left">PUT</td> 
   <td align="left">更新资源</td> 
  </tr> 
  <tr> 
   <td align="left">PATCH</td> 
   <td align="left">部分更新资源</td> 
  </tr> 
  <tr> 
   <td align="left">DELETE</td> 
   <td align="left">删除资源</td> 
  </tr> 
 </tbody> 
</table>

### 3.使用名称 ###

URL指向**资源**，在URL路径的描述中，只需要出现名称，而不要出现动词。动词由HTTP方法提供。  
不要单复数混用，建议名称使用复数。  
Restful的核心是资源，URL应该指向资源，所以应该是使用名称表达式，而不是动词表达。

<table> 
 <thead> 
  <tr> 
   <th align="left">方法</th> 
   <th align="left">路径</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">GET</td> 
   <td align="left"><code>/posts</code></td> 
   <td align="left">返回所有文章</td> 
  </tr> 
  <tr> 
   <td align="left">GET</td> 
   <td align="left"><code>/posts/10</code></td> 
   <td align="left">返回id为10的文章</td> 
  </tr> 
  <tr> 
   <td align="left">POST</td> 
   <td align="left"><code>/posts</code></td> 
   <td align="left">创建新的文章</td> 
  </tr> 
  <tr> 
   <td align="left">PUT</td> 
   <td align="left"><code>/posts/10</code></td> 
   <td align="left">更新id为10的文章</td> 
  </tr> 
  <tr> 
   <td align="left">DELETE</td> 
   <td align="left"><code>/posts/10</code></td> 
   <td align="left">删除id为10的文章</td> 
  </tr> 
  <tr> 
   <td align="left">PATCH</td> 
   <td align="left"><code>/posts/10</code></td> 
   <td align="left">部分更新id为10的文章数据</td> 
  </tr> 
 </tbody> 
</table>

*  不要出现如下的访问路径

/getAllPosts
    /addPost
    /updatePost
    /delPost

*  GET方法只是获取资源，而不是改变资源状态。改变资源请使用POST,PUT,DELETE等方法。
 *  例如：使用`GET /posts/10`就可以获取资源了，但是却使用`Get /posts/10/del`或`GET /posts/10?v=del`,本意是想删除。但这样不好，GET方法请求只为获取资源，不要改变资源状态。
 *  子资源的访问

<table> 
 <thead> 
  <tr> 
   <th align="left">方法</th> 
   <th align="left">路径Endpoint</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">GET</td> 
   <td align="left"><code>/posts/10/authors</code></td> 
   <td align="left">返回id为10的文章的所有作者</td> 
  </tr> 
  <tr> 
   <td align="left">GET</td> 
   <td align="left"><code>/posts/10/authors/8</code></td> 
   <td align="left">返回id为10的文章的作者中id为4的</td> 
  </tr> 
 </tbody> 
</table>

### 4.集合功能 ###

*  过滤Filtering
    
    1.  指定过滤条件`GET /posts?tag=python`
 *  排序Sorting
    
    1.  指定排序条件。有很多种设计风格，例如使用`+`表示asc,`-`表示desc。`GET /posts?sort=+title,-id`获取`GET /posts?sort=title_asc,id_desc`
 *  分页Pagination
    
    1.  一般情况下，查询返回的记录数非常多，必须分页。`GET /posts?page=58&size=20`

### 5.状态码 ###

*  使用HTTP响应的状态码表示动作的成功与否。
 *  2xx表示用户请求服务端成功的处理；4xx表示用户请求的错误；5xx表示服务器端出错了。

<table> 
 <thead> 
  <tr> 
   <th align="left">Status Code</th> 
   <th align="left">说明</th> 
   <th align="left">Method</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">200</td> 
   <td align="left">OK</td> 
   <td align="left">GET</td> 
   <td align="left">成功获取资源</td> 
  </tr> 
  <tr> 
   <td align="left">201</td> 
   <td align="left">CREATED</td> 
   <td align="left">POST,PUT,PATCH</td> 
   <td align="left">成功创建或修改</td> 
  </tr> 
  <tr> 
   <td align="left">204</td> 
   <td align="left">NO CONTENT</td> 
   <td align="left">DELETE</td> 
   <td align="left">成功删除资源</td> 
  </tr> 
  <tr> 
   <td align="left">400</td> 
   <td align="left">Bad Request</td> 
   <td align="left">ALL</td> 
   <td align="left">请求中有错误，例如：GET时参数有问题，PUT时提交的数据错误等</td> 
  </tr> 
  <tr> 
   <td align="left">401</td> 
   <td align="left">Unauthorized</td> 
   <td align="left">ALL</td> 
   <td align="left">权限未通过认证</td> 
  </tr> 
  <tr> 
   <td align="left">403</td> 
   <td align="left">Forbidden</td> 
   <td align="left">ALL</td> 
   <td align="left">有无权限都禁止访问该资源</td> 
  </tr> 
  <tr> 
   <td align="left">404</td> 
   <td align="left">Forbidden</td> 
   <td align="left">ALL</td> 
   <td align="left">请求资源不存在</td> 
  </tr> 
  <tr> 
   <td align="left">500</td> 
   <td align="left">internal Server Error</td> 
   <td align="left">ALL</td> 
   <td align="left">服务器端错误</td> 
  </tr> 
 </tbody> 
</table>

*  详细状态码参考[https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html][https_www.w3.org_Protocols_rfc2616_rfc2616-sec10.html]

### 6.错误处理 ###

*  在Restful API设计中，错误处理也非常重要。单单从无状态码中无法详尽描述错误的信息。

1.  返回消息
    
        { error:"user NOT Found"}
2.  从错误消息中了解到错误号、错误信息、错误描述等信息。甚至更详细的信息可以通过code查阅文档
    
        { 
            "code":10056,
            "message":"Invalid ID",
            "description":"More details"
        }

### 7.版本 ###

*  强烈要求使用版本、版本号使用简单数字，例如v2。
 *  2种风格
    
    1.  `http://api.xdd.com/v1/posts/10` 这种风格会跨域，适合较大的项目
    2.  `http://www.xdd.com/api/v1/posts/10`

### 8. 返回结果 ###

<table> 
 <thead> 
  <tr> 
   <th align="left">方法</th> 
   <th align="left">路径</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">GET</td> 
   <td align="left">/posts</td> 
   <td align="left">返回所有文章的列表</td> 
  </tr> 
  <tr> 
   <td align="left">GET</td> 
   <td align="left">/posts/10</td> 
   <td align="left">返回id为10的文章对象</td> 
  </tr> 
  <tr> 
   <td align="left">POST</td> 
   <td align="left">/posts</td> 
   <td align="left">创建更新的文章并返回这个对象</td> 
  </tr> 
  <tr> 
   <td align="left">PUT</td> 
   <td align="left">/posts/10</td> 
   <td align="left">更新id为10的文章并返回这个对象</td> 
  </tr> 
  <tr> 
   <td align="left">DELETE</td> 
   <td align="left">/posts/10</td> 
   <td align="left">删除id为10的文章返回一个空对象</td> 
  </tr> 
  <tr> 
   <td align="left">PATCH</td> 
   <td align="left">/posts/10</td> 
   <td align="left">部分更新id为10的文章数据并返回这个对象</td> 
  </tr> 
 </tbody> 
</table>

*  **数据一律采用JSON格式**

[https_www.w3.org_Protocols_rfc2616_rfc2616-sec10.html]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html