什么是REST和RESTful API?
REST:(英文:Representational State Transfer,简称REST)表征性状态转移,是一种软件架构风格。
RESTful : RESTful API就是REST风格的API
restFul规范:
1、建议使用https作为网络通信协议
2、接口的url建议加上'api'字符,清晰地表明此url是一个接口
3、接口版本号相关字符v1/v2/v3...建议加在接口的url上,表明当前接口的版本号
4、返回值中包含状态码或者Code,状态码标识当前http请求的响应码,响应码具体表明的状态在http协议里已经做了解释。而code则是对请求返回状态的更细的细分,code弥补了状态码不够用的现实,具体的code表明哪种状态,我们需要跟前端商量决定。
常用状态码:
200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
5、路径,把网路上的任何东西都看作资源,restful协议建议我们使用名词来表明接口url路径path
https://www.luffycity.com/api/v1/animals
6、method:请求方法,restful建议操作同一资源根据不同的http请求方法执行增删改查等不同的操作
GET:从服务器取出资源
POST:创建新的资源
PUT:更新资源的全部属性字段
PATCH:更新资源的局部属性字段
DELETE:从服务器上删除资源
7、过滤筛选,restful建议我们把操作资源时的过滤条件加在url上面,多以查询字符串的方式
https://www.luffycity.com/api/v1/animals?age=10&gender=0
8、错误处理,当返回值的状态码为4XX时,返回错误信息,以便前端展示
return HttpResponse({'detail': '用户名或者密码错误'}, status=400)
9、返回结果,针对不同操作,服务器向用户返回的结果应该符合以下规范(具体是否需要返回须看前端需求)。
GET/collection:返回资源对象的列表(数组)
GET/collection/resource:返回单个资源对象
POST/collection:返回新生成的资源对象
PUT/collection/resource:返回完整的资源对象
PATCH/collection/resource:返回完整的资源对象
DELETE/collection/resource:返回一个空
10、最好做到Hypermedia,即返回结果中提供链接,连向其他API(url),使得用户不查文档,也知道下一步应该做什么
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}