如何设计一个良好的 API接口

如何设计一个良好的 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–账号被锁