类Restful接口设计规范

-- 引言 --
    Restful是一种非常优美的http接口设计风格及设计规范。使用restful原理来设计接口，可以非常显著地降低多个系统之间的耦合性，也可以使得接口变得非常一致，不仅美观，而且容易理解和上手。
    然而在实际工作中，似乎很难真正用上完全的Restful，理想和现实总是有差距的- -
    通过不断地实践归纳，结合restful的核心原理，我小结出了一套类Restful接口规范。它基本上解决了我在项目中遇到的90%的问题，自我感觉良好，哈哈。

-- 正文 --
== 请求/响应规范 ==

请求
GET: 使用url传参，如：?a=1&b=2
POST: 使用Json传参，从request.body中获取此Json，如：'{"a": 1, "b": 2}'

响应
返回值格式为json，分为成功返回（ok_json）和失败返回（fail_json）

ok_json示例：
{"ok": True, data: {"user_id": 1}, "echo": "", "error": "", "reason": ""}

fail_json示例：
{"ok": False, data: {}, "echo": "COMM_INVALID_ARGS", "error": "1001", "reason": "请求参数错误"}


== 接口规范 ==
假设我们的数据模型叫做“User”
注意：
1、以下接口中的“返回值”均为请求成功时的返回值，存在ok_json中的data里
2、在参数前面加上:的（如:user_id），说明此参数非必须；在参数前面加*的（如*user_id），说明此参数必须
3、列表返回值的结果，默认使用id逆序排序，即新建的数据在前。如果你在数据模型中自己定义了display_order，你就使用你的order进行排序


【新增】/user/add/
【请求方式】POST
【描述】提供新建一个User对象所需要的所有属性，新建成功后，将新建数据的id返回
【参数】新建user所需要的所有参数，依据业务不同有所不同
【返回值】：{"id": 3}


【更新】/user/update/
【请求方式】POST
【描述】根据提供的id更新对应记录的属性
【参数】*user_id，*其他待更新的属性值（不包括删除标记）
【返回值】{}


【查看】/user/view/
【请求方式】GET
【描述】提供记录id，返回对象的json化数据
【参数】*user_id
【返回值】{"id": "1", "username": "swpu-lee", "real_name": "lee", "gender": 0, ...}


【删除】/user/delete/
【请求方式】GET
【描述】删除一条数据。在我的实际项目中，往往只是对记录标记以下is_deleted为True。对于所有查询接口来说，被标记为is_deleted的数据都应该查不到（也就是说这些接口在做数据查询时都要加上“is_deleted为False”这个条件）
【参数】*user_id
【返回值】{}


【查询】/user/query/
【请求方式】GET
【描述】获得满足指定过滤条件的数据，这个接口返回满足条件记录的id列表。此接口与实际使用相关，需要自己定义一个查询协议。
【参数】依据实际需求有所不同，如：{"age": "11-20", "eye_color": "red", ...}
【返回值】[1, 2, 3, 5, 78, 121, ...]


【批量查看】/user/view/bulk/
【请求方式】GET
【描述】根据提供的ids批量查看数据。此接口可以配合Query接口进行批量查看
【参数】*user_ids（格式为："1,2,3,4,5"，用逗号隔开）
【返回值】{"1": {用户1的数据}, "2": {用户2的数据}, "3": {用户3的数据}, ...}


### 以下两个接口在这个user的例子中，不是很好体现这个接口的价值，所以我改用“用户相册”的例子
【列表】/photo/album/list/
【请求方式】GET
【描述】查看照片列表，当请求参数中有user_id时，获得指定用户的相册的列表，否则返回全体用户的相册列表。另外此接口需要返回记录总数，这样可以供其他应用做分页使用
【参数】:user_id默认为None，:offset默认0，:limit默认20，返回数据的json列表以及总数据量
【返回值】{"total_count": 101, "list": [{相册1}, {相册2}, {相册3}, ...]}


【全部】/phtot/album/all/
【请求方式】GET
【描述】返回指定用户的所有相册
【参数】*user_id
【返回值】[{相册1}, {相册2}, {相册3}, ...]



-- 结束语 --
    不是每一个接口都必须存在于每一个项目，具体需要哪些接口，根据实际业务需求来添加。
    此种规范的提供的操作全是原子级别的操作，当你要实现某个复杂的需求时，可以通过组合这几个接口实现你需要的功能。
    以上规范并不能解决开发过程中的全部问题（比如密码检查接口，你不可能在数据库中存明文密码吧？）。我的建议是，在遇到问题时，应优先使用这些接口来解决你的问题，不能解决时再考虑开发特殊接口处理。