HTTP(四)Restful Service API设计最佳工程实践

定义一套优秀的Restful APIs

1. API命名应该采用约定俗成的方式, 保持简洁明了;
2. 考虑到系统迭代和兼容性需求, API中应该引入版本规则
3. 优雅的设计条件过滤, 排序, 搜索等传入参数形式
4. 合理设计返回数据的形式, 格式和考虑启用压缩
5. 根据不同的API操作, 设置合适的HTTP状态码和必要的出错信息
6. 使用token机制设计鉴权和验证系统
7. 如何实现数据的分页返回
8. 如何处理有关联资源的返回数据
9. 考虑启用HTTP缓存机制
10. 限制API调用频次
11. 尽可能的使用https, 涉及用户验证的API一定要强制启用https

API命名应该采用约定俗成的方式, 保持简洁明了

{/api/readers/hello}

所有API应该使用REST架构约定形式命名。REST架构的思想是将API请求对象看成一个个资源, 实现者使用相应的HTTP的动词(GET, POST, PUT, PATCH, DELETE)来访问和操作这些资源。为了使API简单明了, 一般使用名词, 而不是动词来命名这些资源

API中资源命名使用复数的形式, 这是一个约定, 可以省去设计时考虑数据具体细节的麻烦。

如何设计一个资源拥有另外一个资源的情况的API, 例如, 设计一个包含用户(users)和用户的评论(comments)的API可以采用这样的形式:

GET /users/1234/comments

GET /users/1234/comments/1

如果一个资源并不依附其他资源可以独立存在, 完全可以使用users一样的形式提供, 如果要查询其中的关系, 可以使用其他资源作为ID的形式来过滤。

考虑到系统迭代和兼容性, 需要在API中引入版本规则

关于设置API的版本信息, 常见的有两种方法, 一种是将版本号放到http header内, 另一种是直接放在URL中。放在URL中是最常见的做法

GET https://api.twitter.com/1.1/friends

如果一个API的版本过期了, 把请求重定向到最新的版本上。比如user API v1版本过期了, 当有调用/api/v1.0/users/1234的时候, 应该被重定向到最新的/api/v2.0/users/1234

优雅的设计条件过滤, 排序, 搜索等传入参数形式

Restful API经常有对返回数据过滤和排序的要求, 这些输入参数推荐采用Http Query Parameter的方式实现

返回所有已经登录的用户        

GET /users?login=true

获取所有的用户, 返回结果按照create_at降序排序

GET /users?sort=-create_at

单独为API设计一个Query Parameters专门用于搜索

GET /users?q=key&&sort=-create_at, login_at&disabled=false

查询数据的部分内容

有些时候资源属性很多, 不同的客户端需要的内容不相同, 可以采用下面的形式来过滤数据的属性

GET /user?fields=id, user_name, address&disabled=false&login_at

GET /facebook/v2.8/me?fields=id, name, birthday, cover, devices, email&access_token=xxx

合理设计返回数据的形式, 格式和考虑启用压缩

API在执行相关的操作之后要把更新后的数据也做为返回值的一部分返回给调用者, 这样可以避免调用者再次调用Get API来获取更新, 而浪费一次http请求。特别是对于POST操作的API, 因为该API会创建数据, 该数据被创建后的唯一性ID由服务端生成, 如果不返回新创建的ID, 客户端就不能基于这个数据做进一步操作。

使用token机制设计鉴权和验证系统

由于Restful API的无状态特性, 我们不能以来请求前后的上下文来做鉴权和用户验证

一个实用的解决方案

1. 用户使用用户名密码或者第三方登录, 最终请求一个登录API
2. 服务器认证成功后, 生成一个token, 并将这个token和用户信息关联在一起, 同时返回这个token给调用客户端
3. 客户端记录并保存下这个token;
4. 下次客户端发起和用户相关请求API都要在http header中带上这个token;
5. 服务端通过这个token去区分用户是谁, 判断这个用户是否已经登录和有什么样的权限;
6. 服务端也要考虑token的失效时间;
7. 客户端在发现token失效的时候重新请求新的token

限制API调用频次(Rate limiting)

如果一个客户端请求API的频率太快, 根据http协议, 可以返回Too Many Requests

如果要为客户端提供更加详细的调用频次和访问次数之类的信息, 除了提供文档说明之外, 还可以在http header 用自定义字段的形式提供

尽可能的使用https, 涉及用户验证的API一定要强制启用https

如果通过http明文传递会有很大的安全问题。如果用于鉴权的app id和Secret, 甚至是用户名密码通过明文传递, 那么很容易被截获和保存, 完全没有安全性。

涉及任何和用户特定信息相关内容API都要通过https暴露给调用者。