实践api设计

加密

防止消息被截取而泄露,通过加密,可以保护消息

https

签名

防止篡改

请求

请求头

请求发起方

请求发起方的身份ID

请求流水号

在请求发起方范围内,唯一标示一笔请求的编号

请求有效期

请求携带timestamp,服务端校验timestamp是否在有效时间窗口范围内(比如:5分钟内),能够避免同一个请求不断的被重复发送。注意客户端和服务器时间都要保持同步。

每页条数

第几页

请求数据

应答

应答头

应答状态

应答码

应答描述

每页条数

第几页

总条数

应答数据

登录

jwt

幂等

API版本设计

API版本号传递方式,一般包括如下几种:

  • API版本号放在URL路径中,比如:http://api.***.com/v1/book
  • API版本号放在URL参数中,比如:http://api.***.com/book?version=v1.0
  • API版本号放在请求的header中,比如:Accept: application/json; version=1
  • API版本号放在二级域名中,比如:http://v1.api.***.com
  • API版本号放在请求消息中

API多版本管理势必会带来开发和维护的复杂度,如果使用方单一,也可以不需要版本管理,协调使用方配合一起升级。如果使用方众多,难以协调一致,则还是应该加入版本管理,确保生态稳定。

参考

设计 RPC 接口时,你有考虑过这些吗?