RESTful API设计技巧

「爱情、让人受尽委屈。」 2022-04-01 03:51 152阅读 0赞

第一部分会介绍RESTful基本的设计指南，第二部分则会详细介绍具体设计中碰到的问题。  
原文： [https://note.youdao.com/share/?id=63a093cabbe9c85412ddfc9213b798e5&type=note\#/][https_note.youdao.com_share_id_63a093cabbe9c85412ddfc9213b798e5_type_note]

# URL基本构成 #

![image][]

## 域名 ##

如图所示，URL的第一部分是域名加上“/api/”或直接将API融入域名中，来表明这是一个用于API的专属链接。

## 模块名 ##

紧接着是一个模块名，表示该API所在的具体的业务模块，像谷歌就有youtube, drive等等。但如果你的API只对应单一的业务，这一部分是可以省略的。  
Spotify的API只对音乐提供不同的接口，就省略了这一部分。

## 版本号 ##

基本上大多数的API提供方都会把版本号放在URL内，通常发布后的REST服务不会在同一个版本内做大的改动。

## 资源名 ##

资源名的设计需要遵循一定的原则，这些原则会让你的API看起来更加清晰、统一以及易用，但这并不是强制性的规范。

*  使用名词  
    动词都将被转移至HTTP动词，资源名词和HTTP动词的结合能更清晰地表现出API的操作
 *  使用复数  
    不管这个资源是不是一个列表或组合，都用复数来表现，可以减轻设计者的头疼，也可以避免冗余的相近的API
 *  使用英文小写
 *  避免使用下划线“\_”，用横线“-”代替

## 参数 ##

当需要对URL返回的资源进行过滤或者筛选时，就需要用到参数。

常见的URL参数分两种，一种是直接写在URL内的，也被成为URL变量，如下的1：

https://www.sampleapis.com/drive/v2/files/1

另一种是加在URL的最后，通常作为查询参数：

https://www.sampleapis.com/drive/v2/files?id=1

# HTTP动词 #

HTTP动词可以表明对资源的增删改查操作，它们的具体含义如下：

<table> 
 <thead> 
  <tr> 
   <th>动词</th> 
   <th>具体操作</th> 
   <th>返回消息体</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>GET</td> 
   <td>获取资源</td> 
   <td>返回资源对象</td> 
  </tr> 
  <tr> 
   <td>POST</td> 
   <td>新增资源</td> 
   <td>返回新增的资源对象或资源的位置</td> 
  </tr> 
  <tr> 
   <td>PUT</td> 
   <td>完整地替换资源</td> 
   <td>返回修改后的资源对象或资源的位置</td> 
  </tr> 
  <tr> 
   <td>PATCH</td> 
   <td>更新资源的部分信息</td> 
   <td>返回修改后的资源对象或资源的位置</td> 
  </tr> 
  <tr> 
   <td>DELETE</td> 
   <td>删除资源</td> 
   <td>无需返回消息体</td> 
  </tr> 
 </tbody> 
</table>

# HTTP状态码 #

HTTP状态码作为HTTP请求的返回的一部分，已经能涵盖非常多的状态信息，这边只列举了一些常用的状态码：

<table> 
 <thead> 
  <tr> 
   <th>状态码</th> 
   <th>具体信息</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>200 OK</td> 
   <td>服务器返回成功，通常会附带消息体</td> 
  </tr> 
  <tr> 
   <td>201 Created</td> 
   <td>新建或修改服务器的成功</td> 
  </tr> 
  <tr> 
   <td>202 Accepted</td> 
   <td>请求已被接服务器接收并开始处理，用于异步处理</td> 
  </tr> 
  <tr> 
   <td>400 Bad Request</td> 
   <td>请求有错误，服务器未处理（4开头的错误码通常都是客户端发出的请求有问题）</td> 
  </tr> 
  <tr> 
   <td>404 Not Found</td> 
   <td>未找到请求的资源</td> 
  </tr> 
  <tr> 
   <td>409 Confilct</td> 
   <td>通常是对已经存在的资源进行了重复创建，服务器认为是冲突</td> 
  </tr> 
  <tr> 
   <td>500 Internal Server Error</td> 
   <td>服务器发生错误（5开头的错误码通常是服务器端发生异常）</td> 
  </tr> 
 </tbody> 
</table>

# 认证 #

RESTful API一般建议使用OAuth2.0的框架做身份认证，配合以JWT作为Token的格式。OAuth2.0保证了RESTful API的无状态性。

# REST API 设计技巧 #

## URL变量还是参数？ ##

上面有提到，取一个id为1的资源时，可以使用URL变量（resources/1）或是URL参数(resources?id=1)的方式。但是如果要取得id从1到5的资源，URL变量就会变得很奇怪了，这时候使用URL参数就更加合适。URL参数也可以用来做分页、排序等功能。

## 非增删改查的操作 ##

HTTP动词能够表示对资源的增删改查操作，可是如果是其他的操作呢？比如播放、喜欢歌曲，启动、关闭系统…这时候HTTP动词好像就无能为力了。传统的API设计方法如下：

/songs/1/play
    /songs/1/like

可这样不是违反了URL中不能出现动词的规则了吗？但这确实是一种解决方法，而且许多大公司也这样做，这样的API其实足够清晰易用，没什么理由能够让人拒绝。

如果一定要遵守不出现动词的规则，下面有一个方法，也可以试一下：

/songs/1?operation=play
    /songs?id=1,2,3,4,5&operation=like

这个方法的还有一个好处在于，它可以同时对多个资源进行操作。无论选择哪种形式，记得在你的API里保持一致性。

# 文档 #

RESTful API绝对需要良好的文档说明，文档不仅可以帮助API使用者了解具体的数据格式以及资源请求方式，也可以帮助API开发者在版本演技和维护时，不断审视需求等。

RESTful文档通常需要包含具体的URL资源以及对应的各种HTTP动词的操作解释、请求和返回的格式、示例请求等

[https_note.youdao.com_share_id_63a093cabbe9c85412ddfc9213b798e5_type_note]: https://note.youdao.com/share/?id=63a093cabbe9c85412ddfc9213b798e5&type=note#/
[image]: /images/20220401/f632d5270ef74b4e83f58902cb27ccd2.png