Vary's Blog

Server API 设计

设计

使用 RESTful 风格的 API 设计。

协议

使用 HTTPS 协议,保证 HTTP 的方便的同时保证一定的安全性。

域名

尽量部署在专属域名下,如 github:

https://api.github.com/

版本

应该把版本号放到 URL 中,如 API 有改版的时候,应保证老版的 API 持续提供服务一段时间。

https://api.example.com/v1/

路径和资源

在 Restful 风格的 API 中,每个路径都代表着互联网中的一个资源。所以 URL 地址中应该使用名词,并且因为大多是资源集合,所以应该使用复数形式。如果是有从属关系的资源,应该服从从属关系,下面给出几个例子:

  • https://api.example.com/v1/posts
  • https://api.example.com/v1/posts/{postId}
  • https://api.example.com/v1/posts/{postId}/comments

HTTP 动词

HTTP 动词可以完美对应数据库的增删查改操作,于是我们就把 HTTP 动词和我们的增删查改操作对应起来:

  • GET:查询数据
  • POST:增加数据
  • PUT:更新数据(客户端提供改变后的完整资源)
  • PATCH:更新数据(客户端更新某几条属性)
  • DELETE:删除数据

    示例

    下面是结合 HTTP 动词和路径提供一些示例:

  • GET /posts :获取所有文章

  • POST /posts :创建一篇文章
  • GET /posts/{postId} :获取指定 Id 的文章信息
  • PUT /posts/{postId} :修改指定 Id 的文章信息(客户端需要提供全部属性)
  • PATCH /post/{postId} :修改指定 Id 的文章信息(客户端提供需要修改的部分属性)
  • DELETE /post/{postId} :删除指定 Id 的文章
  • GET /posts/{postId}/comments :获取指定 Id 文章的所有评论
  • POST /posts/{postId}/comments :在指定 Id 文章下创建一条评论

Query 查询

在 GET 查询的时候我们不可能一次性获取所有资源,那么我们需要提供一些查询条件。

下面是一些常用的查询:

  • ?index=2&size=20:第二页每页20条
  • ?sortby=name&order=asc:第二页每页20条

全局信息

全局通用信息应该放在请求头里,避免使用 Query 拼接,如:

  • APPID(Android/iOS/H5)
  • APPVER(版本号)
  • CHANNEL(渠道号)
  • APP-BUILD-NUM(内部小版本号)
  • TOKEN
  • NETWORK(网络环境)
  • LANGUAGE(语言)

传输数据

Request

使用 json 格式传输数据,如果需要上传文件则使用表单的形式提交。

Response

使用 json 格式传输数据,Content-Type一致设定为application/json
响应格式应该统一,下面给出一个例子:

名字 类型 含义
code int 状态码
message String 状态信息
data List or Object 数据
time long 时间戳

具体的响应如下:

1
2
3
4
5
6
{
'code': 0,
'message': '获取成功',
'data': [], // 返回一个集合
'time': 1472435695000
}

或者返回某一个数据:

1
2
3
4
5
6
{
'code': 0,
'message': '获取成功',
'data': {}, // 返回一个对象
'time': 1472435695000
}

安全

为了保证客户端与服务端通信的安全,我们使用 HTTPS 协议。

在身份认证上使用 Oauth 2.0 协议,用户登录之后在客户端保存一份 token,避免在客户端持久化存储用户名和密码。之后每次访问需要身份认证的 API 时,必须携带 token 访问。

避免空指针

API 设计的时候应该合理帮助前端避免空指针异常,在一些字段或者属性为空的时候应该返回默认值:如 String 返回"", int 返回0, Object 返回 {}, Array or List 返回 []

Vary Zhao wechat
欢迎你扫描上面的二维码,加我微信