restful api 实践总结

就现在最主流的 restful api 使用规范的一些总结
总体来说 restful api 只是一种接口规范 使 url 请求与数据返回语义化, 便于开发人员理解和使用

从URL设计上来说, 就是 => 动词 + 宾语

1. protocol: 尽量 使用 https 协议

2. url = apiroot/ + (version)/ + resources + (?params)

apiroot 根入口应该简单可配置
(version) 必要的时候可以加上版本控制, 也可以嵌入到 apiroot 里
resources 请求的资源的 名词复数 形式
params 多余的参数可以用键值对拼在后面
注意: url 应该全部用小写,用下划线链接两个单词, resources资源用复数形式 通俗易读,但是不要暴露服务器架构

例如:

https://api.example.com/v1/zoos/{zoo}/animals?animal_types=tiger&page=2&page_size=10
要尽量避免层级过深 和 重要的参数暴露

3. url并不能明显展示请求的目的, 所以配合 http 动词 来表达 CRUD

GET 获取资源信息
POST 创建新的资源
PUT 更新资源
PATCH 在服务器更新资源
DELETE 必须

有多余的参数可以在 复数名词 后加问号拼接
?animal_type_id=1：指定筛选条件
?page=2&per_page=100：指定第几页，以及每页的记录数

4. 有授权的 用 OAuth2.0 的方式为 API 调用者提供登录认证

即: 先通过 登录接口获取 Access Token 后再通过该 token 调用需要身份认证的 API
每个 http 请求头里加上 “access_token”: “token….” 字段

5. 响应应为 json 数据格式, http状态码 明确可查

HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
  "code": 0,
  "msg": "success",
  "data": {
      "username": "username"
  }
}

状态码必须精确

2xx：操作成功
201: 表示生成了新的资源
202: Accepted状态码表示服务器已经收到请求，但还未进行处理，会在未来再处理，通常用于异步操作
204: 表示资源已经不存在

3xx：重定向
302 307: 暂时重定向 用于GET请求
303: 重定向到另一个 URL, 用于POST、PUT和DELETE请求。收到303以后，浏览器不会自动跳转，而会让用户自己决定下一步怎么办

4xx：客户端错误
400 Bad Request：服务器不理解客户端的请求，未做任何处理
401 Unauthorized：用户未提供身份验证凭据，或者没有通过身份验证
403 Forbidden：用户通过了身份验证，但是不具有访问资源所需的权限
404 Not Found：所请求的资源不存在，或不可用
405 Method Not Allowed：用户已经通过身份验证，但是所用的 HTTP 方法不在他的权限之内
406 不支持客户端指定的数据格式
408 Request Timeout 请求超时
409 Gonfilct 请求存在冲突无法处理, 如通过手机号码提供注册功能,当用户提交的手机号已存在时
410 Gone：所请求的资源已从这个地址转移，不再可用
415 Unsupported Media Type：客户端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客户端要求返回 XML 格式
422 Unprocessable Entity
429 Too Many Requests：客户端的请求次数超过限额

5xx：服务器错误 一般来说，API 不会向用户透露服务器的详细信息，所以只要两个状态码就够了
500 Internal Server Error：客户端请求有效，服务器处理时发生了意外
503 Service Unavailable：服务器无法处理请求，一般用于网站维护状态

赏

1分也是爱

微信