REST接口规范总结

逃离我推掉我的手 2021-09-20 06:36 411阅读 0赞

## 1 REST ##

REST是一种软件架构风格，如果你的接口是REST接口，那么该接口可被认为是`REST风格`的。  
REST接口是围绕`资源`展开的，HTTP 的`URL`即资源，利用HTTP的协议，其实rest本也可以和HTTP无关，但是现在大家普遍的使用REST都是依托于HTTP协议。

## 2 URI语法 ##

`URI = scheme “://” authority “/” path [ “?” query ][ “#” fragment ]`

scheme: 指底层用的协议，如http、https、ftp
    host: 服务器的IP地址或者域名
    port: 端口，http中默认80
    path: 访问资源的路径，就是咱们各种web 框架中定义的route路由
    query: 为发送给服务器的参数
    fragment: 锚点，定位到页面的资源，锚点为资源id

## 3 URL路径 ##

*  3.1 endpoint

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

举例来说，有一个API提供学校的信息，包括各个班级，老师，同学的信息，则它的路径应该设计成下面这样：

https://school/v1/classes
        https://school/v1/teachers
        https://school/v1/students

*  3.1 URL规则
 *  1 名词对应数据库中的表
 *  2 URL中不能有动词
 *  3 URL结尾不应该包含斜杠“/”
 *  4 正斜杠分隔符”/“必须用来指示层级关系
 *  5 使用连字符”-“来提高URL的可读性，而不是使用下划线”\_”
 *  6 URL路径中首选小写字母
 *  7 URL路径名词均为复数

## 4 HTTP动词 ##

对于`URL资源`的具体操作类型，由`HTTP动词`表示。  
常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

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

## 5 资源过滤 ##

如果只需要查询某些条件的数据API应该提供参数，过滤返回结果。  
下面是一些常见的参数：

?limit=10：指定返回记录的数量
        ?offset=10：指定返回记录的开始位置。
        ?page=2&per_page=100：指定第几页，以及每页的记录数。
        ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
        ?teacher_subject=语文：指定筛选条件

## 6 返回 ##

> 返回状态码推荐标准HTTP状态码

有很多服务器将返回状态码一直设为200，然后在返回body里面自定义一些状态码来表示服务器返回结果的状态码。  
由于REST API是直接使用的HTTP协议，所以它的状态码也要尽量使用HTTP协议的状态码。

200 OK 服务器返回用户请求的数据，该操作是幂等的
    201 CREATED 新建或者修改数据成功
    204 NOT CONTENT 删除数据成功
    400 BAD REQUEST 用户发出的请求有问题，该操作是幂等的
    401 Unauthoried 表示用户没有认证，无法进行操作
    403 Forbidden 用户访问是被禁止的
    422 Unprocesable Entity 当创建一个对象时，发生一个验证错误
    500 INTERNAL SERVER ERROR 服务器内部错误，用户将无法判断发出的请求是否成功
    503 Service Unavailable 服务不可用状态，多半是因为服务器问题，例如CPU占用率大，等等
    ......

返回结果

GET 		/teachers 返回资源列表
    GET 		/teachers/:id 返回单独的资源
    POST 		/teachers 返回新生成的资源对象
    PUT 		/teachers/:id 返回完整的资源对象
    PATCH	/teachers/:id 返回被修改的属性
    DELETE 	/teachers/:id 返回一个空文档