(完整word版)RESTful-API设计规范.doc

API规范技术部代码规范API设计规范V1.0总览前言为了开发人员快速理解，掌握API的含义，能望文生义，提高沟通交流效率。为什么要API统一规范？阅读方便、爽，因为遇到和自己不同的书写和规范时会感觉很不爽。同时也是考虑到API安全问题，所有的API开发必须遵循oAuthor协议。适用人员API代码开发和代码Review的相关人员。范围定义和术语不可使用-规范中涉及的不可使用的内容，坚决不能使用建议使用-规范中涉及的建议使用的内容，结合实际业务需求，开发习惯，最大程度的符合规范。必须使用-规范中涉及的必须使用的内容，所有研发人员严格按照规范进行开发相关引用文档HYPERLINK"http://www.ruanyifeng.com/blog/2014/05/restful_api.html"http://www.ruanyifeng.com/blog/2014/05/restful_api.htmlHYPERLINK"http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html"http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html规范内容2.1版本应该将API的版本号放入URL。示例：https://example.org/api/v1/2.2URI定义路径又称"终点"（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）：从服务器删除资源。2.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签名算法意义：防止关键业务数据被纂改，保证数据的安全性与完整性。算法：Md5(secret+wubanf_param_json+timestamp)