API规范文档

URI命名规范

1. URI应全部小写，多个字母之间用横杆`-`分割，比如：/dts-admin/job-info/alarm-email-groups

2. URI用于表示资源,所以URI应该用名词表示，动作表示应该通过GET，POST来区分

3. 内外部URI通过URI中的private来区分

   1. 外部URI命名：/业务系统名称/版本号/具体业务，比如：/moh-api/v1/order

   2. 内部URI命名：/业务系统名称/private/版本号/具体业务，比如：/moh-api/private/v1/order

API版本规范

1. 通过在URI中加版本号来区分不同版本的URI

2. 一般情况下，不需要升级版本号，除非出现接口不兼容或其他必须通过升级版本号才能解决问题的情况

API接收数据处理规范

1. API需要尽可能的保证幂等性

2. API需要用户或卖家的id的时候，应该优先考虑从token中获取

3. 调用方在调用API时，必需设置超时时间，被调用方应尽可能的保证在超时时间内返回数据

4. API处理中不应存在大的事务，如果有，应该将大的事务拆分成多个小的事务

5. JWT token的签名和验签统一调用core-library的方法

API数据响应规范

1. 用户或卖家敏感数据禁止直接返回，应脱敏之后返回

2. 数据应该按需返回，不应返回多余的数据

3. 对于安全性较高的系统，可以考虑对数据进行加签，防止无效请求、重放攻击，保证双方通信消息的安全性和真实性

4. 响应数据形式一般为json格式，至少要包含code和message，code为0表示处理成功，其他则表示处理失败，失败具体原因需要查看message

   1. 成功响应:{“code“:0,”message”:”Succeeded”}

   2. 失败响应:{“code“:”10000010”,”message”:”Invalid message status value'}

5. 建议每个业务系统应该定义自己独立的code，这样在客户或前端提供错误码的时候，能快速的知道，是哪个系统返回的错误码，比如：moh的code以10开头，inv的code以11开头

6. 业务系统根据http code返回相应的状态

   1. 200---表示请求接受成功

   2. 400---表示请求参数错误，比如参数校验不通过

   3. 401---表示请求未授权，比如用户未登录

   4. 403---表示请求被拒绝，比如token验证失败

   5. 404---表示请求资源不存在，比如账户不存在，订单不存在

   6. 429---表示请求过多，比如服务内部限流

   7. 500---表示系统错误