一、API接口规范
1.协议:API与客户端用户的通信协议,推荐使用http协议,同时兼容HTTP,以确保交互数据的传输安全。
2.域名:应该尽量将API部署在专用域名之下。http://api.xxx.com
如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。http://www.xxx.com/api/
3.版本:推荐将API的版本号放入URL。
http://api.xxx.com/app/v1.0/foohttp://api.xxx.com/app/v1.1/foohttp://api.xxx.com/app/v2.0/foo
另一种做法是,将版本号放在HTTP头信息中,但不如放入URL方便和直观。
4.路径:路径又称"终点"(endpoint),表示API的具体网址,每个网址代表一种资源(resource)。
接口命名应该是一个动宾结构,由动词 名词组成,采取驼峰式命名规范,例如:
product/v1.0/getProducts 获取产品order/v1.1/saveOrder 保存订单。
二、接口安全规范
1.安全设计规范
(1)app_id和app_key可以直接通过平台线上申请,也可以线下直接颁发。app_id是全局唯一的,每个app_id将对应一个客户,app_key需要客户端高度保密。
(2)timestamp是时间戳,使用系统当前的unix时间戳。时间戳的目的就是为了减轻DDOS的攻击。防止请求被拦截后一直尝试请求接口。服务器端设置时间戳阀值,如果请求时间戳和服务器时间超过阀值,则响应失败。
(3)request_id是随机值。随机值主要是为了增加sign的多变性,也可以保护接口的幂等性,相邻的两次请求reqeust_id不允许重复,如果重复则认为是重复提交,响应失败。
(4)sign是参数签名,将所有非空参数按照升续排序、app_key、timestamp、reqeust_id拼接起来进行md5加密(当然使用其他方式进行不可逆加密也没问题)。
(5)token作为系统调用的唯一凭证,token可以设置一次有效,也可以设置时效性,这里推荐设置时效性。
如果一次有效的话这个接口的请求频率可能会很高。token推荐加到请求头上,这样可以跟业务参数完全区分开来。
2.客户端IP白名单
ip白名单是指将接口的访问权限对部分ip进行开放。这样就能避免其他ip进行访问,设置ip白名单比较麻烦的一点就是当你的客户端进行迁移后,就需要重新联系服务提供者添加新的ip白名单。
设置ip白名单的方式很多,除了传统的防火墙之外,spring cloud alibaba提供的组件sentinel也支持白名单设置。
为了降低api的复杂度,推荐使用防火墙规则进行白名单设置或者在API网关层面设置IP白名单,比如shenyu网关支持IP白名单设置。
3.单个接口针对IP限流
限流是为了更好的维护系统稳定性。使用redis进行接口调用次数统计,ip 接口地址作为key,访问次数作为value,每次请求value1,设置过期时长来限制接口的调用频率。不过这里还是推荐在网关层面进行设置,比如shenyu网关支持IP限流。