我的API定义规范(未完待续,欢迎指正)
项目用途:
API是提供接口服务的,应该为不同的用途设置一个名称。如用于gis展示的api,可以定义为gisapi
版本号:
api开发后,难免会进行修改完善,为避免互相影响,最好加个版本号区分。
以我经常使用codeIgniter框架提供api为例,在CI实现的时候,将用途与版本号,组合成一项,就是控制器名,这个控制类单独有一个代码文件,也是控制器的代码文件名,如gisapi2,表示用于gisapi的版本2,如果不加数字,则表示这个控制器只有默认版本。项目或版本变更时,就应该用不同的代码文件来提供,避免调试部署时影响其它用户。
表示动作:
list列表
get取值
add创建
update更新
delete删除
表示对象:
如position表示点位,user表示用户
动作与对象组合成一项,用驼峰形式,考虑到将同一类对象的方法可以排序放在一块,所有对象在前,动作在后的组合方式,如userAdd,userUpdate,positionList,在CI里,这一项对应的就是"方法函数"
参数:
数据参数:
查询时的查询条件,创建和更新时提供的值,删除时要提供的id等。创建和更新时,参数的名称和参数的值,就表示了要设置的字段的值。
查询参数
但查询参数的问题是,除了“=”情况外,其中最好能能有其他表达式,如是“模糊等于”,“大于小于”等等。如:
name3参数:表示name字段中包含某个值,这个3表示运算符“包含”的意思,即sql查询中like %...%
name8=1234:name包含"1234"的记录
region_code9=1234:region_code以“1234”打头的记录
region_code6=1234:region_code以“1234”结尾的记录
返回结果参数
需要一批固定的保留词
分页查询参数
page:页
limit:取多少条记录
一种是不分层参数
一种是分层参数,用json来传递
HTTP方法,按实际情况取GET/PUT/POST等
key_index=1:如果指定,则输出的json带有key