Web API系列(一)设计经验与总结

在移动互联网的时代, Web服务已经成为了异构系统之间的互联与集成的主要手段,各种 Web服务几乎都采用REST风格的Web Api来构建。 通过Http协议的形式来. 以Get/Post方式发送请求, 返回json格式(数据更小巧且自描述能力强)的数据。这里就不在介绍REST API 的好处和不足。这些网上一大堆资料。今天就说说,如何构建优秀的REST API ?

目前,各大互联网公司, 对自身的REST Api设计有各自的标准,他们的Api 的设计也非常成熟。 那么,我们应该如何更好的设计我们的接口, 来提高我们 API 的可用性,易用性,可维护性与可扩展性呢?

一. API 设计方案
1. Http的请求分为URL约定规则、请求参数规则
URL规则: http://{server}/{product}/{version}/{logic}/{method}?{query_string}

server: 为具体的服务域名
product: 为应用工程名
version: 为具体版本号, 便于将来的功能扩展, 可以暂定为 v1, v2
logic: 为具体业务逻辑的初步划分, 比如后端管理方法, app端的请求方法
method: 具体业务的方法

具体的请求参数, 由指定的method方法决定, 全都作为HTTP GET/POST的参数列表。

这里很多人会问为什么把 method 和 version 放到在URI中?

因为这样可以使API 版本化,方便版本控制,同时也便于日后API的分流。当然关于是否将版本信息放入url还是放入请求头里面,曾经有过很激烈的争论,各有各的道理。我个人认为放到 URL 中会好一些。具体的大家还是根据自己的业务场景,综合考量吧。

2. Http的响应规则
HTTP响应码为200, 返回结果为JSON字符串的形式:
如果响应结果正确,则返回结果如下所示:
{
data : { // 请求数据,对象或数组均可
user_id: 123,
user_name: “zwz”,
user_avatar_url: “http://www.abc.com/1.jpg”

},
msg : “done”, // 请求状态描述,调试用
success : 1,
code” : 1001, // 业务自定义状态码
extra : { // 其他扩展的数据,字段、内容不定
type: 1,
desc: “签到成功!”
}
}

如果响应结果失败,则返回如下结果:
{
data : { // 请求数据,对象或数组均可
},
msg : “Internal Server Error”, // 请求状态描述,调试用
success : 0,
code : 5001, // 业务自定义状态码
extra : {
}
}

 

3. Auth 权限验证

API 的权限验证,有很多方案,目前成熟的OAuth 2.0框架等,不过 ,最简单的还是利用 Http Header 来完成这一目标。 将token 通过 Header 传递。来实现权限验证。

4. API 在设计的时候,最好不要将业务错误码与HTTP状态码的绑定,重新定义一套业务错误码,来区分HTTP 的状态码。
状态码的定义也最好有一套规范,类似于HTTP 的状态码,可以按照用户相关、授权相关、各种业务,做简单的分类。
// Code 业务自定义状态码定义示例
// 授权相关
1001: 无权限访问
1002: access_token过期
1003: unique_token无效

// 用户相关
2001: 未登录
2002: 用户信息错误
2003: 用户不存在

// 业务相关
3001: 业务XXX
3002: 业务XXX

// 系统异常
5001:Internal Server Error

二. 其他一些建议:

1. 规范统一的命名
使用驼峰式或者下划线格式都可以,统一规范就行。不过,目前基本都是统一小写加下划线比较好。如:user_id,user_name,user_age等。

2. 语义清晰,遵守常用缩写
字段的名字最好能体现字段的类型,遵守一些常用的缩写,如:user_name, task_desc, date_str 等

3. 空值、空字段的处理
空值、空字段的处理也是比较容易出问题。统一空值用null 。除了布尔类型的,其余的空值统一用null表示,客户端保证每种字段的null可以被正常处理。

4. 各个Action 尽量符合CRUD操作的原则。

5. 给不同类型设置默认空值
除了null,尽量对字段设置“默认值”,如数字就是0,字符串就是空字符串””,数组就是空数组[],对象就是空对象{},这样可以避免客户端处理空值产生的异常。
具体的要根据业务、前后端约定而定。
比如,bool 类型的值,统一成数字0和1 。时间日期类型强制只能传标准GMT/UTC时间戳,然后由各自的客户端根据自己的时区、显示要求做处理后显示。

6. 完整的URL
API里面的数据也会有URL类型的,一般来说如用户的头像、各种图片、音频等资源,都是以URL链接的形式返回的。
返回的URL一定要“完整”,主要指的是不要忘记URL里面的协议部分。应该是http://www.abc.com/1.jpg。

7. REST 安全
可以使用固有的 HTTP 基本验证,你还可以考虑通过支持表单验证,LTPA 验证,Open ID 验证等方式,来满足更多的企业安全要求。

8. 尽量将API部署在专用域名之下。例如:https://api.example.com。

9. API返回的数据格式,应该尽量使用JSON,避免使用XML。

10. 返回正确 HTTP 响应代码,同时重新定义一套业务错误码,来区分HTTP 的状态码。

11. 完善的文档,最好能自动生成在线API文档,这样文档能随时保持最新。
目前有很多自动生成API 文档的攻击,例如:SwaggerUI。

 

发表评论

电子邮件地址不会被公开。