RESTful-API设计规范.docx

API规范 技术部代码规范API设计规范V1.01. 总览1.1. 前言为了开发人员快速理解，掌握API的含义，能望文生义，提高沟通交流效率。1.2. 为什么要API统一规范？阅读方便、爽，因为遇到和自己不同的书写和规范时会感觉很不爽。同时也是考虑到API安全问题，所有的API开发必须遵循oAuthor协议。1.3. 适用人员API代码开发和代码Review的相关人员。1.4. 范围1.5. 定义和术语 不可使用- 规范中涉及的不可使用的内容，坚决不能使用建议使用- 规范中涉及的建议使用的内容，结合实际业务需求，开发习惯，最大程度的符合规范。必须使用- 规范中涉及的必须使用的内容，所有研发人员严格按照规范进行开发1.6. 相关引用文档/blog/2014/05/restful_api.html/blog/2014/05/oauth_2_0.html 72. 规范内容2.1 版本 应该将API的版本号放入URL。示例 ：/api/v1/2.2 URI定义路径又称终点（endpoint），表示API的具体网址。在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的集合（collection），所以API中的名词也应该使用复数。Example ：以动物园集合为例 GET /zoos：列出所有动物园POST /zoos：新建一个动物园GET /zoos/ID：获取某个指定动物园的信息PUT/zoos/ID：更新某个指定动物园的信息 DELETE /zoos/ID：删除某个动物园2.3 过滤 （供参考）l ?page=2&pageSize=100：指定第几页，以及每页的记录数。l ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。l ?animal_type_id=1：指定筛选条件2.4 HTTP 动词规范常用的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 签名