你必须掌握的 RESTful 后端接口设计参考书-CSDN博客

RESTful

RESTful 是 HTTP 协议的一种规则

HTTP服务可用端口最大为 65535

HTTP URL

http://domain:addr/path?query#anchor

domain  # 域名地址
addr    # 端口:HTTP:80/HTTPS:443
path    # 资源路径
query   # 资源筛选参数
anchor  # 锚点:页面定位
复制代码

RESTful API —— 设计要素

1.请求方法

| POST   | 提交 | 返回: 提交的信息
| GET    | 获取 | 返回: 获取到的数据
| PUT    | 替换 | 返回: 被替换的完整信息
| PATCH  | 更新 | 返回: 仅被更新的字段
| DELETE | 销毁 | 返回: 204
复制代码

2.资源路径

http://api.example.com/v1/assets/id

http://      # 请求协议
api.         # API子域
example.com  # 域名
/v1          # API版本
/assets      # 资源路径（复数）
/id          # 资源Id
复制代码

3.过滤信息

Query

基本格式: url?key=value
多个条件: url?key=value&key=value
分页示范: url?page=2
复制代码

4.状态代码

常用的响应状态码

200 —— OK                    // 成功返回
201 —— Created               // 成功创建
204 —— No Content            // 成功销毁
400 —— Bad Request           // 语法错误
401 —— Unauthorized          // 没有权限
403 —— Forbidden             // 请求被拒
404 —— Not Found             // 找不到资源
500 —— Internal Server Error // 内部服务器错误
501 —— Not Implemented       // 服务器无法受理
复制代码

5.返回响应信息

{
    "code": 200,
    "message": "",
    "body": ""
}
复制代码

完整的 HTTP 状态码

响应: HTTP/1.1 200 OK

1xx（临时响应）

100 —— Continue             // 继续请求，服务器正在等待
101 —— Switching Protocol   // 服务器准备切换协议
103 —— // 一个新的状态码，可以让服务器在主标题之前尽早发送标题，这有助于预加载等优化
复制代码

2xx（响应成功）

200 —— OK                   // 成功返回了资源
201 —— Created              // 成功创建了资源
202 —— Accepted             // 请求接受但未处理
203 —— Non-Authoritative Information // 返回资源未授权
204 —— No Content           // 成功销毁了资源
205 —— Reset Content        // 重置内容，无任何资源返回
206 —— Partial Content      // 处理了部分请求
复制代码

3xx（请求重定向）

300 —— Multiple Choice      // 选择服务器提供的多种操作
301 —— Moved Permanently    // 永久移除，自动转跳到新的资源
302 —— Found                // 自动转跳到新的资源
303 —— See Other            // 查看资源位置
304 —— Not Modified         // 请求资源未修改
305 —— Use Proxy            // 需要代理
307 —— Temporary Redirect   // 临时重定向
308 —— Permanent Redirect   // 永久重定向
复制代码

4xx（请求错误）

400 —— Bad Request              // 请求字段语法错误
401 —— Unauthorized             // 请求未经授权
403 —— Forbidden                // 请求被服务器拒绝
404 —— Not Found                // 找不到资源
405 —— Method Not Allowed       // 请求方法不允许
406 —— Not Acceptable           // 请求不可接受
407 —— Proxy Authentication Required // 服务器代理需要授权
408 —— Request Timeout          // 请求超时
409 —— Conflict                 // 请求冲突
410 —— Gone                     // 请求的资源已销毁
411 —— Length Required          // 指定有效内容长度标头
412 —— Precondition Failed      // 请求条件无法满足
413 —— Payload Too Large        // 请求体过大
414 —— URI Too Long             // 请求URL过长
415 —— Unsupported Media Type   // 请求的类型不支持
416 —— Requested Range Not Satisfiable // 请求的范围不符合要求
417 —— Expectation Failed       // 服务器未满足请求标头的要求
426 —— Upgrade Required         // 升级所需
428 —— Precondition Required    // 要求先决条件
429 —— Too Many Requests        // 太多的要求
431 —— Request Header Fields Too Large // 请求头字段太大
451 —— Unavailable For Legal Reasons  // 因法律原因不可用
复制代码

5xx（服务器错误）

500 —— Internal Server Error        // 内部服务器错误
501 —— Not Implemented              // 服务器无法受理
502 —— Bad Gateway                  // 服务器网关错误
503 —— Service Unavailable          // 服务器不可用
504 —— Gateway Timeout              // 服务器代理超时
505 —— HTTP Version Not Supported      // 不支持的HTTP版本
511 —— Network Authentication Required // 网络认证要求
复制代码