阅读 26

漫谈Web API的设计-总结

1. API的概念

Application Programming Interface.应用编程接口,早期开发Win32或者MFC的程序员非常的熟悉。添加Web前缀之后,就变成了Web API。主要前后端开发过程中,程序交互使用的接口。

2. Web API包含内容

  1. 地址
  2. 请求方式
  3. 请求参数
  4. 返回参数
  5. 其他

3. Web API的设计步骤

  1. 确定功能需求,根据页面和本身业务逻辑设计相应的接口
  2. 选择承载技术。比如目前基于流行的RESTful风格,采用HTTP+JSON的方式居多。
  3. 确定接口风格。有遵循SOAP协议的web service风格,有基于HTTP+JSON的restful风格等。
  4. 定义接口形式

4.1 条件查询

/books/123 //查询id为123的图书详情信息
/books/123/price //查询id为123的图像价格
复制代码

4.2 消息正文封装

{
    "name":"xxx",
    "companyId":"1001",
    "age":30,
    "address":{
        "city":"suzhou",
        "road":"kejicehng ..."
    }
}
复制代码
  • 传递唯一业务字段,比如name
  • 传递唯一id,比如companyId,对于companyName是不需要前端传入,后台应该是有能力根据companyId获取到对应的companyName。
  • 传递关联对象。传入数据关联了其他对象数据。

4.3 响应和异常设计

实际开发中,常见响应和异常设计如下:

成功

{
    "message":"ok",
    "success":true,
    "entity":{
        //对象或者数组
    }
}
复制代码

失败

{
    "message":"新建用户失败",
    "success":false,
    "entity":null
}
复制代码

更多

很多使用的API也通过聚合在市场上,通过次数计费。实际开发过程中,我们可以直接购买付费的API,快速的开发我们自己的业务。www.juhe.cn/