当前位置:首页 > 建筑/环境 > 工程监理 > RESTful-API设计规范
技术部代码规范API设计规范V1.0API规范21.总览1.1.前言为了开发人员快速理解,掌握API的含义,能望文生义,提高沟通交流效率。1.2.为什么要API统一规范?阅读方便、爽,因为遇到和自己不同的书写和规范时会感觉很不爽。同时也是考虑到API安全问题,所有的API开发必须遵循oAuthor协议。1.3.适用人员API代码开发和代码Review的相关人员。1.4.范围1.5.定义和术语不可使用-规范中涉及的不可使用的内容,坚决不能使用建议使用-规范中涉及的建议使用的内容,结合实际业务需求,开发习惯,最大程度的符合规范。必须使用-规范中涉及的必须使用的内容,所有研发人员严格按照规范进行开发1.6.相关引用文档://规范3API规范42.规范内容2.1版本应该将API的版本号放入URL。示例:定义路径又称终点(endpoint),表示API的具体网址。在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的集合(collection),所以API中的名词也应该使用复数。Example:以动物园集合为例GET/zoos:列出所有动物园POST/zoos:新建一个动物园GET/zoos/ID:获取某个指定动物园的信息PUT/zoos/ID:更新某个指定动物园的信息DELETE/zoos/ID:删除某个动物园2.3过滤(供参考)?page=2&pageSize=100:指定第几页,以及每页的记录数。?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。?animal_type_id=1:指定筛选条件2.4HTTP动词规范常用的HTTP动词有下面4个(对应SQL的命令)GET(SELECT):从服务器取出资源(一项或多项)。POST(CREATE):在服务器新建一个资源。PUT(UPDATE):在服务器更新资源。DELETE(DELETE):从服务器删除资源。API规范52.5请求格式请求数据格式统一json请求数据格式如下:wuBaNfJson={params:{key1:value1,key2:value2},secret:123456780233FA31AD94AA59CFA65305,timestamp:20151101095440000000,sign:E981702AF260F37FCCD7D60FD19AAEA7}2.6返回格式返回数据格式统一JSON数据结果如下:{errcode:0,//提示码errmsg:ok,//提示信息data:{接口返回的数据}//请求失败返回可以为空,成功为非空}Errcode状态码汇总表状态码说明0表示成功-1表示系统繁忙101表示解析JSON内容错误102表示签名错误500表示系统错误2.7签名算法API规范6意义:防止关键业务数据被纂改,保证数据的安全性与完整性。算法:Md5(secret+wubanf_param_json+timestamp)
本文标题:RESTful-API设计规范
链接地址:https://www.777doc.com/doc-4449716 .html