api设计规范

简介: 我们通常的GET和POST同RESTFul中的GET、POST是不一样的。通常使用GET、POST的选择点在于,简单的用GET、复杂对象用POST,并没有动作的含义,例如我也可以使用get来执行添加的动作,如果参数很多,我也可以使用POST来执行查询操作;但在REST里,GET对应的是查询一个资源,

前言

说到restful,其实我们并不完全遵循restful规范。我们会参考restful的设计理念,并且结合我们自己的一些实践来对web api进行设计。

我们一起来看看RESTFul API有哪些特点:

  1. 基于“资源”,数据也好、服务也好,在RESTFul设计里一切都是资源。GET:查询,POST:新增,PUT:更新,DELETE:删除
  2. 无状态。一次调用一般就会返回结果,不存在类似于“打开连接-访问数据-关闭连接”这种依赖于上一次调用的情况。
  3. URL中通常不出现动词,只有名词
  4. URL语义清晰、明确,使用HTTP的GET、POST、DELETE、PUT来表示对于资源的增删改查
  5. 返回结果使用JSON不使用XML

网站:/get_user?id=100
RESTFul: GET /user/100 (GET是HTTP类型)

*我们通常的GET和POST同RESTFul中的GET、POST是不一样的。通常使用GET、POST的选择点在于,简单的用GET、复杂对象用POST,并没有动作的含义,例如我也可以使用get来执行添加的动作,如果参数很多,我也可以使用POST来执行查询操作;但在REST里,GET对应的是查询一个资源,而POST对应的是新增一个资源,意义是决然不同的。理解这一点非常重要。

规范

  1. api 接口必须加版本号,初始版本 【v1】
  2. 不使用rest的PUT和DELETE,因为很多浏览器不支持,很多框架也不支持
  3. POST在需要传输大量数据的时候使用,其余使用GET就可以了;
这里GET和POST没有明确的含义,GET也可以新增
  1. 所有路径path全部小写,以下划线分隔,所有参数,包括POST里面的body,以及header。例如:http://127.0.0.1/v1/wechat/mch_info/list_mch_info?page=2&per_page=100
  2. 我们返回一般统一使用json格式返回
  3. 在url上必须包含行为
  4. 使用Token令牌来做用户身份的校验与权限分级,而不是Cookie
  5. 暴露外部请求一定使用SSL

Path具体的实现

path = /{版本}/{具体的业务功能}/{表名}/{行为}

1.{版本}:开始时全部为V1,
2.{具体的业务功能}:

App的setting,数据库命名为 app_setting
那么,具体的业务功能=setting
架构组的wechat,数据库命名为arch_wechat
那么,具体的业务功能=wechat

  • {表名}:就是数据的表名
  • {行为}:一般就是方法名
  • limit=10:指定返回记录的数量
  • offset=10:指定返回记录的开始位置。
  • page=2&per_page=100:指定第几页,以及每页的记录数。
  • sort_by=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
http协议 方法 行为path 说明
POST add(POJO) /add 添加一个对象,接收json信息
GET insert(param …) /insert?param1=?&param1=? 插入一个对象,多个参数的方式,作用和add一样,只是传参数方式不同
GET deleteById(long) /delete_by_id?id=? 数据库不删除,但是业务上有删除的语意
POST update(POJO) /update
GET updateById(long) /update_by_id?id=? {表名}中已经具体指明了实体,所有这里可以不用update_pojo_by_id
GET getById(long) /get_by_id?id=? {表名}中已经具体指明了实体,所有这里可以不用get_pojo_by_id
GET listByParam(Object) /list_by_param?param=? &page=2&per_page=100 list查询多个,默认全部,可以带上limit,offset,page,sort_by,order等参数
1.参考数据库设计 
2.【推荐】表的命名最好是加上“业务名称_表的作用”。       
3.正例: user / trade_config
4.【推荐】库名与应用名称尽量一致,{业务项目}_{功能},业务项目和功能怎么写参考

Response

  • 采用JSON,不要使用XML
  • 默认情况下要支持gzip
  • 格式统一:
{
      "code" : 0,
      "msg" : "Something bad happened",
      "data" : {

      }
    }
  • code: 0为成功,非0为失败。可以自定义code,代表不同的错误码
  • msg: 当code为非0时,获取错误信息。当code为0时,msg一般为”success”。如果有需要也可以另外作规定
  • data: 当code为0时,获取结果,全部以json方式表示。当code为非0时,data没有数据

错误处理

不要直接将异常抛给客户端处理,一般需要一个统一的异常处理类,并且以统一格式将异常信息返回前端,统一格式参照“# Response”

相关文章
|
JSON 负载均衡 前端开发
一文带你详细了解Open API设计规范
一文带你详细了解Open API设计规范
3444 1
|
存储 缓存 安全
API接口设计规范
这个是目前第三方数据接口交互过程中常用的一些参数与使用示例,希望对大家有点帮助。 当然如果为了保证更加的安全,可以加上RSA,RSA2,AES等等加密方式,保证了数据的更加的安全,但是唯一的缺点是加密与解密比较耗费CPU的资源.
|
6月前
|
SQL API Python
Python DB API下规范下cursor对象常用接口
Python DB API下规范下cursor对象常用接口。
87 4
|
4月前
|
安全 前端开发 API
ThinkPHP5 API模块开发规范与示例
【7月更文挑战第6天】本技术文档旨在指导开发者如何完全遵循ThinkPHP5框架的开发规范来构建RESTful API模块。ThinkPHP5(简称TP5)是一款基于PHP的轻量级MVC框架,其简洁、高效的特点非常适合快速开发Web应用及API接口。以下是创建API模块的基本步骤、最佳实践以及代码示例。
184 0
|
5月前
|
存储 Java API
JavaSE——常用API进阶二(2/8)-BigDecimal(BigDecimal的常见构造器、常用方法,用法示例,使用规范)
JavaSE——常用API进阶二(2/8)-BigDecimal(BigDecimal的常见构造器、常用方法,用法示例,使用规范)
43 1
|
6月前
|
JSON Java API
Springboot项目中如何设计一个规范的统一的Restful API 响应框架?
Springboot项目中如何设计一个规范的统一的Restful API 响应框架?
65 1
|
缓存 API 数据格式
要调用API接口获取商品数据,首先需要了解该API的文档和规范
要调用API接口获取商品数据,首先需要了解该API的文档和规范。大多数API都需要使用API密钥进行身份验证,因此您需要先注册API提供商,并从他们那里获取API密钥
|
6月前
|
移动开发 小程序 JavaScript
【uniapp 小程序开发页面篇】代码编写规范 | 页面编写规范 | 小程序API
【uniapp 小程序开发页面篇】代码编写规范 | 页面编写规范 | 小程序API
291 0
|
11月前
|
安全 API 数据安全/隐私保护
API 接口设计规范
API 接口设计规范
417 0
|
API
钉钉的API规范
钉钉的API规范
239 2