RESTful api最佳实践

RESTful API设计最佳实践

RESTful

Representational State Transfer 资源层状态转移, 是一种网络应用程序的设计风格和开发方式，基于http，可以使用XML格式定义或JSON格式定义。

REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。

RESTful架构是对MVC架构改进后所形成的一种架构，通过使用事先定义好的接口与不同的服务联系起来。在RESTful架构中，浏览器使用POST，DELETE，PUT和GET四种请求方式分别对指定的URL资源进行增删改查操作。因此，RESTful是通过URI实现对资源的管理及访问，具有扩展性强、结构清晰的特点。

1,协议

使用http或者https, 对外如有安全性要求, 可以使用https, 但是内部服务间调用可以使用http或https

2,HTTP方法

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

常用方法(动词)	说明
GET	获取资源
POST	创建资源
PUT	更新资源
PATCH	更新部分资源
DELETE	删除资源

3,使用名词

URL指向资源, 在URL路径描述中, 只需要出现名词, 而不要出现动词, 动词由http的请求方法提供, 也不要单复数混用, 建议名词使用复数

方法	路径	说明
GET	/posts	返回所有文章
GET	/posts/5	返回id为5的文章
POST	/posts	创建新的文章
PUT	/posts/5	更新id为5的文章
DELETE	/posts/5	删除id为5的文章
PATCH	/posts/5	部分更新id为5的文章数据

不要出现类似下面的访问资源的路径

/getAllPosts
/addPost
/updatePost
/delPost

GET方法只是获取资源, 而不是改变资源状态, 改变资源请使用POST, PUT, DELETE等方法

例如使用 GET/posts/10 就可以获取资源了, 不要使用GET/posts/10/del或者GET/posts/10?v=del,本意是像删除, 但这样不好, GET方法请求只为获取资源, 切记不要改变资源状态

子资源的访问

方法	路径	说明
GET	/posts/10/authors	返回id为10的文章的所有作者
GET	/posts/10/authors/8	返回id为10的文章的作者中id为4的

4,集合功能

过滤Filtering
指定过滤条件:

GET/posts?tag=python

排序Sorting
指定排序条件, 有很多种设计风格, 例如使用+表示asc升序, -表示desc降序:

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

分页Pagination
一般情况下, 查询返沪ide记录非常多, 必须分页:

GET/posts?page=5&size=20

5,状态码

使用http响应的状态码表示动作的成功与否

2xx表示用户请求被服务器成功处理; 4xx表示用户请求错误; 5xx表示服务器错误

status code	说明	Method	说明
200	OK	GET	成功获取资源
201	CREATED	POST, PUT, PATCH	成功创建或需改
204	NO CONTENT	DELETE	成功删除资源
400	Bad Request	ALL	请求中有错误
401	Unauthorized	ALL	权限未通过认证
403	Forbidden	ALL	有无权限都禁止访问该资源
404	Not Found	ALL	资源不存在
500	Internal Server Error	ALL	服务器错误

6,错误处理

在Restful api中, 错误处理也非常重要, 单单从状态码中无法详尽描述错误信息

1.返回消息

{
"error":"User Not Found"
}

2.从错误消息中了解到错误号, 错误信息, 错误描述等信息, 甚至更详细的信息可以通过code查阅文档, code为0表示无错误, 非0表示有错误, 具体看message中的描述了

{
"code":1005,
"message":"Invalid ID",
}

7,版本

强烈要求版本号使用简单数字, 例如v3

http://localhost:8000/v3/post/10

8,返回结果

方法	路径	说明
GET	/posts	返回所有文章列表
GET	/posts/10	返回id为10的文章对象
POST	/posts	创建新的文章并返回这个对象
PUT	/posts/10	更新id为10的文章并返回这个对象
DELETE	/posts/10	删除id为10的文章返回一个空对象
PATCH	/posts/10	部分更新id为10的文章数据并返回这个对象

osts/10 | 更新id为10的文章并返回这个对象 |
| DELETE | /posts/10 | 删除id为10的文章返回一个空对象 |
| PATCH | /posts/10 | 部分更新id为10的文章数据并返回这个对象 |

返回数据一律采用JSON格式