RESTful API 编写指南
Posted by Gevin (/users/gevin/) on 2016/06/06, 8:43 am
Category:
微
服
务
(/?category=
微
服
务
)
Tags: RESTful (/?tag=RESTful) flask (/?tag=flask) django (/?tag=django) OAuth (/?
tag=OAuth)
基于一些不错的RESTful开发组件,可以快速的开发出不错的RESTful API,但如果不了解
开发规范的、健壮的RESTful API的基本面,即便优秀的RESTful开发组件摆在面前,也无
法很好的理解和使用。下文Gevin结合自己的实践经验,整理了从零开始开发RESTful API
的核心要点,完善的RESTful开发组件基本都会包含全部或大部分要点,对于支持不够到位
的要点,我们也可以自己写代码实现。
Outline
Request 和 Response
Serialization 和 Deserialization
Validation
Authentication 和 Permission
CORS
URL Rules
1. Request 和 Response
RESTful API的开发和使用,无非是客户端向服务器发请求(request),以及服务器对客
户端请求的响应(response)。本真RESTful架构风格
(http://blog.igevin.info/posts/restful-architecture-in-general/)具有统一接口的特
点,即,使用不同的http方法表达不同的行为:
GET(SELECT):从服务器取出资源(一项或多项)
POST(CREATE):在服务器新建一个资源
PUT(UPDATE):在服务器更新资源(客户端提供完整资源数据)
PATCH(UPDATE):在服务器更新资源(客户端提供需要修改的资源数据)
DELETE(DELETE):从服务器删除资源
客户端会基于 GET 方法向服务器发送获取数据的请求,基于 PUT 或 PATCH 方法向服务器发送
更新数据的请求等,服务端在设计API时,也要按照相应规范来处理对应的请求,这点现在
应该已经成为所有RESTful API的开发者的共识了,而且各web框架的request类和
response类都很强大,具有合理的默认设置和灵活的定制性,Gevin在这里仅准备强调一
下响应这些request时,常用的Response要包含的数据和状态码(status code),不完善
的内容,欢迎大家补充:
当 GET , PUT 和 PATCH 请求成功时,要返回对应的数据,及状态码 200 ,即SUCCESS
当 POST 创建数据成功时,要返回创建的数据,及状态码 201 ,即CREATED
当 DELETE 删除数据成功时,不返回数据,状态码要返回 204 ,即NO CONTENT
当 GET 不到数据时,状态码要返回 404 ,即NOT FOUND
任何时候,如果请求有问题,如校验请求数据时发现错误,要返回状态码 400 ,即
BAD REQUEST
当API 请求需要用户认证时,如果request中的认证信息不正确,要返回状态码 401 ,
即NOT AUTHORIZED
当API 请求需要验证用户权限时,如果当前用户无相应权限,要返回状态码 403 ,即
FORBIDDEN