如何设计一个良好的 API接口
在设计接口时,有很多因素要考虑,如接口的业务定位,接口的安全性,接口的可扩展性、接口的稳定性、接口的跨域性、接口的协议规则、接口的路径规则、接口单一原则、接口过滤和接口组合等诸多因素。
职责原则:在设计接口时,必须明确接口的职责,即接口类型,接口应解决什么业务问题等。
单一性原则:在明确接口职责的条件下,尽量做到接口单一,即一个接口只做一件事,而非两件以上。
协议规范:在设计接口时,应明确接口协议,是采用 HTTP协议,HTTPS协议还是 FTP协议,要根据具体情况来定。
FTP协议(File Transfer Protocol,简称FTP),是一套标准的文件传输协议,用于传输文件,如.txt,.csv等,一般文件传输,采用FTP协议;
HTTP协议,适用一般对安全性要求比较低或没要求的业务情景;
HTTPS=HTTP+SSL,适用于对安全性要求较高的业务情景;
路径规则:由于 api获取的是一种资源,所以网址中尽量为名词,而非动词。
http请求方式:接口基本访问协议:get(获取),post(新增),put(修改)和delete(删除)。
域名:一般地,域名分为主域名和专有域名,主域名适合 api长期不变或变化较少的业务,专有域名是解决具体的专有业务的。
跨域考虑:在明确域名的情况下,一定要考虑接口是否跨域,以及跨域应采用的技术手段等。
api版本:对于接口的url,应加版本号http://api.demo.com/v{d}/,其中 d表示版本号,如v1.0,v2.0。
适度过滤信息:当记录数比较多时(如 SELECT * FROM TBName),因适当添加一些条件对数据进行过滤,如TOP,分页,分组,排序和 WHERE条件等。
返回数据格式:返回数据格式,一般包括三个字段:
【1】失败情况(状态码、错误码和错误描述)
{
“status”:0,//状态码 0-表示失败,1-表示成功
“error_code”:“2003”,//错误码,一般在设计时定义
“error_des”:“身份验证失败”//错误描述,一般在设计时定义
}
【2】成功情况(标识id,数据对象,状态码)
{
“sid”:“sh20190111”,//token id
“users”:{
“id”:“al201901111341”,//用户id
“name”:“Alan_beijing”,//用户名
“addr”:“用户地址”
},
“status”:1//状态码 0-表示失败,1-表示成功
}
安全性原则:接口暴露的考虑,接口并发量的考虑(限流),接口防攻击的考虑(黑白名单),接口跨域的考虑等。
可扩展性原则:在设计接口时,充分考虑接口的可扩展性。
定义api界限:任何api,从权限上,可归结为匿名 api和非匿名 api,前者不需要验证,后者需要验证。
定义api返回码:在 api设计时,要定好 api返回码,如:
1 --授权过期
404–未找到资源
500–内部服务器错误
600–账号被锁