API设计 #

设计前提 #

• GET：表示查询时需支持幂等。
  • 使用 GET 时地址栏会暴露给所有用户，可能会被运营商缓存，被 Nginx、应用自身的日志等记录，所以 GET 参数不应该包含任何敏感信息。
  • 某些 SDK、客户端、代理可能会自动重试 GET 请求，所以要么 GET 都支持幂等，要么更换其它 HTTP 方法。
• POST：表示创建时不支持幂等。
• PUT：表示全部更新时可以支持幂等。
• PATCH：表示局部更新时可以支持幂等。

Restful接口 #

查询接口 #

按客户端类型返回

• GET /movies/100?format=full
• GET /movies/100?format=mobile

筛选字段

• GET /movies/100?fields=title,kind,rating
• GET /movies/100?exclude=actors
• GET /movies/100?includes=actors.name

条件过滤

• GET /movies?state=onshow&title=superman
• GET /movies?id=100,200

分页查询

• GET /movies?offset=20&limit=10
• GET /movies?last_id=10&limit=10

显示详情

• GET /movies/100

修改接口 #

• PUT /movies/100/avatar
  • 创建或修改某个资源下的所有属性（通过payload指定）。
• PATCH /movies/100
  • 只修改某个资源下的部分属性（通过payload指定）。
• POST /movies/100/score?add=10
  • 将资源的某个属性值加10。

RPC接口 #

此处的RPC接口特指那些不涉及到资源修改的功能。

• GET /translate?from=en_US&to=zh_CN&text=Hello
• GET /calculate?x=100&y=200

接口版本号 #

• 版本号通过请求头version插入