RESTful api接口规范

深碍√TFBOYSˉ_ 2022-03-07 20:08 308阅读 0赞

> 域名

应该尽量将API部署在专用域名之下。

[https://api.example.com][https_api.example.com]

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

[https://example.org/api/][https_example.org_api]

> api版本控制

应该将API的版本号放入URL。

[https://api.example.com/v\{n\}/][https_api.example.com_v_n]

v\{n\} n代表版本号,分为整形和浮点型

整形的版本号: 大功能版本发布形式；具有当前版本状态下的所有API接口 ,例如：v1,v2

浮点型：为小版本号，只具备补充api的功能，其他api都默认调用对应大版本号的api 例如：v1.1 v2.2

> API 路径规则

路径又称"终点"（endpoint），表示API的具体网址。

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/v1/products
    
    https://api.example.com/v1/users
    
    https://api.example.com/v1/employees

> HTTP请求方式

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面四个（括号里是对应的SQL命令）。

*  GET（SELECT）：从服务器取出资源（一项或多项）。
 *  POST（CREATE）：在服务器新建一个资源。
 *  PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
 *  DELETE（DELETE）：从服务器删除资源。

下面是一些例子。

GET /product：列出所有商品
    
    POST /product：新建一个商品
    
    GET /product/ID：获取某个指定商品的信息
    
    PUT /product/ID：更新某个指定商品的信息
    
    DELETE /product/ID：删除某个商品
    
    GET /product/ID/purchase ：列出某个指定商品的所有投资者
    
    get /product/ID/purchase/ID：获取某个指定商品的指定投资者信息

> 过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。

?limit=10：指定返回记录的数量

?offset=10：指定返回记录的开始位置。

?page=2&per\_page=100：指定第几页，以及每页的记录数。

?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

?producy\_type=1：指定筛选条件

# 注意点 #

*  资源路径

对于rest资源的定义，即URL的定义，是最重要的；想要设计出优雅的、易读的rest 接口，其实还是听不容易的。

*  URL中不能有动词

在Restful架构中，每个网址代表的是一种资源，所以网址中不能有动词，只能有名词，动词由HTTP的 get、post、put、delete 四种方法来表示。

*  URL结尾不应该包含斜杠“/”

这是作为URL路径中处理中最重要的规则之一，正斜杠（/）不会增加语义值，且可能导致混淆。REST API不允许一个尾部的斜杠，不应该将它们包含在提供给客户端的链接的结尾处。

*  正斜杠分隔符”/“必须用来指示层级关系  
    rul的路径中的正斜杠“/“字符用于指示资源之间的层次关系。

例如：

[http://api.user.com/schools/grades/classes/boys][http_api.user.com_schools_grades_classes_boys] //学校中所有的男生  
[http://api.college.com/students/3248234/courses][http_api.college.com_students_3248234_courses] //检索id为3248234的学生学习的所有课程的清单。

*  URL路径名词均为复数  
    为了保证url格式的一致性，建议使用复数形式。
 *  RESTful API对资源的操作  
    对于rest api资源的操作，由HTTP动词表示

# 参考文献 #

[Restful api接口规范][Restful api]

[https_api.example.com]: https://api.example.com
[https_example.org_api]: https://example.org/api/
[https_api.example.com_v_n]: https://api.example.com/v%7Bn%7D/
[http_api.user.com_schools_grades_classes_boys]: http://api.user.com/schools/grades/classes/boys
[http_api.college.com_students_3248234_courses]: http://api.college.com/students/3248234/courses
[Restful api]: https://blog.csdn.net/u010622769/article/details/54341363/