Restful API 接口规范

1、路径

1. 在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。且一般为复数。
2. "/“只是⼀个分隔符，”/“不应该出现在URL的末尾。如果访问到末尾含有”/“的地址，应该重定向到没有”/"的地址。
3. /{version}/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

 

2、方法

对于资源的具体操作类型，由HTTP动词表示，HTTP动词主要有以下几种，括号中对应的是SQL命令。

1. GET（SELECT）：从服务器取出资源（一项或多项）；

2. POST（CREATE）：在服务器新建一个资源；

3. PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）；

4. PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）；

5. DELET（DELETE）：从服务器删除资源；

6. HEAD：获取资源的元数据；

7. OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

 

3、过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户，API会提供参数，过滤返回结果，常见的参数有：

1. ?limit=20

   指定返回记录的数量为20；

2. ?offset=8

   指定返回记录的开始位置为8；

3. ?page=1&per_page=50

   指定第1页，以及每页的记录数为50；

4. ?sortby=name&order=asc

   指定返回结果按照name属性进行升序排序；

5. ?animal_type_id=2

   指定筛选条件。

 

4、状态码

使用适合的状态码很重要，而不应该全部都返回状态码 200

1. 200~299段 表示操作成功：

   200 操作成功，正常返回

   201 操作成功，已经正在处理该请求

2. 300~399段 表示参数方面的异常

   300 参数类型错误

   301 参数格式错误

   302 参数超出正常取值范围

   303 token过期

   304 token无效

3. 400~499段 表示请求地址方面的异常：

   400 找不到地址

   403 权限不足

   404 找不到资源

4. 500~599段 表示内部代码异常：

   500 服务器代码异常

 

5、返回数据

尽量使用json，避免使用xml

  
 

参考链接
https://blog.csdn.net/qq_38423105/article/details/120722022
https://blog.csdn.net/a2398936046/article/details/124764479

 
如有不对，烦请指出，感谢~