API架构设计

接口设计

*.Restful API

[概述] REST是指表现层状态转移(Representational State Transfer). 该概念首次出现在2000年Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一. 其中，表现层是资源的表现层，对于网络中的资源就需要URI来定位.

1.协议

使用http或https. 对外有安全性要求时可食用https. 但内部服务器间调用可使用http或https(从效率角度通常使用http).

2.请求方法(动词)

3.请求路径(名词)

[概述] Restful风格中，使用名词作为路径. URL用于指向资源，路径描述中只使用名次，不要出现动词，动词由HTTP方法提供.且名词不要单复数混用，建议全部使用复数形式. Restful的核心是资源，URL应该指向资源，所以应该使用名次表达，而非动词.

4.集合功能(查询)

过滤Filtering: 可以通过查询字符串指定筛选条件

• 指定过滤条件GET /users/posts?tag=python

排序Sorting: 设计方式有很多，例如可以使用+表示升序(asc)，-表示降序(desc)

• GET /users/posts?sort=+title,-id
• GET /users/posts?sort=title_asc,id_desc

分页Pagination

• 如一页查20个，查第5页: GET /posts?page=5&size=20

5.状态码

• 2xx为成功；4xx为请求错误；5xx为服务端错误

6.错误处理

• 方法一: 通过仅返回错误信息的方式实现错误处理，错误信息不为空就是有错误.

{
		"error": 'User Not Found'
}

• 方法二: 通过返回更详细的错误信息来实现错误处理，甚至更详细的信息可以通过code查阅文档(通常错误为0表示无错误).

{
		"code": 10056,
  	"message": "Invalid ID",
  	"description": "More details"
}

7.接口版本

• 风格一: http://api.demo.com/v1/posts => 这种风格会跨域，适合较大的项目. 通常用于SOA架构的项目.
• 风格二: http://www.demo.com/api/v1/posts

8.返回结果