Restful API设计最佳实践

1. Restful

REST(Representational State Transfer)，表现层状态转移。它首次出现在2000年Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一。 表现层是资源的表现层，对于网络中的资源就需要URI(Uniform Resource Identififier)来指向。

1.1协议

使用HTTP或者HTTPS。对外若有安全性要求，可以使用HTTPS。但是内部服务间调用可以使用HTTP或HTTPS。

1.2 http方法

HTTP请求中的方法表示执行的动作

 1.3 使用名词

URL指向资源，在URL路径的描述中，只需要出现名词，而不要出现动词。动词由HTTP方法提供。 不要单复数混用，建议名词使用复数。 Restful的核心是资源，URL应该指向资源，所以应该是使用名称表达，而不是动词表达。

GET方法只是获取资源，而不是改变资源状态。改变资源请使用POST、PUT、DELETE等方法。例如，使用 GET /posts/10 就可以获取资源了，但是却使用 GET /posts/10/del 或 GET /posts/10?v=del ，本意 是想删除。但这样不好，GET方法请求只为获取资源，不要改变资源状态。

1.4 集合功能

过滤 Filtering：指定过滤条件 GET /posts?tag=python

排序 Sorting：指定排序条件。有很多种设计风格，例如使用+表示asc，-表示desc。 GET /posts?sort=+title,-id 或 GET /posts?sort=title_asc,id_desc

分页 Pagination：一般情况下，查询返回的记录数非常多，必须分页。 GET /posts?page=5&size=20

1.5 状态码

使用HTTP响应的状态码表示动作的成功与否。2XX表示用户请求被服务器端成功的处理；4XX表示用户请求的错误；5XX表示服务器端出错了。

 1.6 错误处理

在Restful API设计中，错误处理也非常重要。单单从状态码中无法详尽描述错误的信息

1、返回消息：{error:"User Not Found" }

2、从错误消息中了解到错误号、错误信息、错误描述等信息。甚至更详细的信息可以通过code查阅文档。

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

1.7 版本

强烈要求使用版本，版本号使用简单数字，例如v2。

2种风格 ：

• http://api.magedu.com/v1/posts/10 这种风格会跨域，适合较大的项目
• http://www.magedu.com/api/v1/posts/10

1.8返回结果

返回数据一律采用JSON格式。