序
本文主要研究下rest api的设计。
设计准则
- easy to use & hard to misuse
易用不易误用，也就是api设计不要太复杂，要简单易用，而且还不能容易用错。
- least astonishment
简单就好，不要试图提供其他花哨、华丽的额外功能，比如对于时间类似的字符串参数，规定好一个输入格式即可，不要试图同时兼容多种格式输入。
- use case & document story
api文档要围绕story或者use case来进行，在一个业务场景下提供完整的闭环操作。
输入规范
- url中的参数
避免驼峰，避免下划线，优先采用横杠
- request method
post表示新增(
url中没有id)，delete表示删除，get表示查询，put表示全量更新(幂等操作)，post url中携带id也可用于表示更新。
- 分页
比如page及size，或者limit及offset
- 排序
比如sort=+field2,-field2，用逗号分隔多个排序字段，用+表示升序，用-表示降序
- 字段过滤
比如fields=field1,field2,field3
- 复杂查询
简单的比如用eq代表等，lt代表小于，lte代表小于等于，gt代表大于，gte代表大于等于，like代表模糊查询；更复杂的话，可以参考rsql规范。
- 版本
不建议版本化，建议采用新的领域命名才与原有的api区分开来
输出规范
- 返回码
遵循http的返回码规范，4xx表示客户端错误，5xx表示服务端错误。
- 返回jsonObject而不是jsonArray
顶层结构返回jsonArray的话，就不容易扩展了。一般返回jsonObject，通常会携带code，error之类的
- 返回jsonObject的字段
success表示请求是否成功，data表示数据，msg表示消息描述，error描述错误信息详情。
- 错误信息格式
type表示错误异常类型，code表示错误编号用于个性化错误提示，msg用于错误信息描述，link提供该错误信息的具体描述页面
安全相关
- 调用方鉴权
对于api的消费者，要求调用的时候强制提供appId及appKey，用于最基本的调用源的鉴权
- 细粒度鉴权
对于更细粒度的数据权限控制，要细化到url及requestMethod基本
- 参数校验
对于查询、修改等参数要做基本校验，对参数内容进行非法参数过滤。
- 屏蔽错误堆栈
不要暴露后端的错误堆栈，如果是要方便排查问题，可以设置一个开关，来设置是否屏蔽错误堆栈
- 敏感数据脱敏
对于敏感的数据，要适当做一些脱敏处理，比如身份证号，手机号等。在真正需要真实数据的话，需要额外进行请求。
- 账号密码需要加密
登陆接口必须走https，而且必须要有图形验证码，而且还必须防暴力破解，有错误锁定机制，对于密码的传递，必须加密处理
- 防止id遍历问题
对于url的参数，如果id是递增的，则需要处理遍历问题，要么对外暴露经过处理后的id，要么做数据权限控制
- 防止token replay
对于token要有一定的失效机制，另外建议token对url参数进行签名
- 防止文件下载目录遍历
对于提供文件下载的接口，一定要避免目录遍历问题
服务质量保障
- 提供SLA
- 提供流量管理、熔断、限流
- 提供服务扩容机制
- 提供故障演练
- 提供审计功能
- 监控异常流量
- 提供调用方间的隔离
小结
rest api的设计牵扯的方面比较多，本文暂时只是先列了一些，后续有待补充。