DRF使用篇（一）:什么是restful

什么是restful

RESTful是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。
它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，
更易于实现缓存等机制。

• REST本身并没有创造新的技术、组件或服务，而隐藏在RESTful背后的理念就是使用Web的现有
  特征和能力， 更好地使用现有Web标准中的一些准则和约束。虽然REST本身受Web技术的影响
  很深， 但是理论上REST架构风格并不是绑定在HTTP上，只不过目前HTTP是唯一与REST相关的
  实例。 所以我们这里描述的REST也是通过HTTP实现的REST。 RESTful的核心操作：URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。
  那这种风格的接口有什么好处呢？可以前后端分离。前端拿到数据只负责展示和渲染，不对数
  据做任何处理。后端处理数据并以JSON格式传输出去，定义这样一套统一的接口，在web， ios，android三端都可以用相同的接口。

• REST全称是Representational State Transfer，中文意思是 表征状态转移 。 它首次出现在2000年 Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一。 他在论文中提到："我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。" 如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

一个好的RESTful接口需要遵循以下规范

1. 域名

专属 API 域名的接口: https://api.example.com

2. 版本

• API 的版本号应该写入到 URL 路径中:
  http://www.example.com/app/1.0/foo
  or
  http://www.example.com/app/1.1/foo,
• 或者把版本号放到请求头中:
  Accept: vnd.example-com.foo+json; version=1.0
  or
  Accept: vnd.example-com.foo+json; version=2.0

3. 路径

• 路径 endpoint 表示 API 的具体网址, 每个 URl 代表一个资源 resource
• 资源作为网址的时候, 约定俗成, 只能有名词, 不能有动词,利用 HTTP 的请求方式可以确定操作
• 请求路径中, 名词应该为复数http://127.0.0.1:8000/users

4. HTTP请求方式释义:

• GET : 从服务器获取资源,一个或者多个: users/:获取所有用户, users/1 获取pk为 1 的用户
• POST : 在服务器新建一个资源: users/ 请求体中需要包含创建用户的信息
• PUT : 在服务器更新资源(客户端提供改变后的完整资源): users/1请求体包含pk为1的用户的全部必传信息
• PATCH : 在服务器更新资源(局部更新某资源的单独字段): users/1请求体包含pk为1的用户的某个字段的信息
• DELETE : 从服务器删除资源: users/1 删除 pk 为 1的用户全部信息
• OPTIONS : 获取信息,关于资源的哪些属性是客户端可以改变的

5. 过滤信息

如果返回的信息过多,服务器不应该一次性给客户端返回全部的结果,API应该提供参数过滤返回结果

• ?limit=10：指定返回记录的数量
• ?offset=10：指定返回记录的开始位置。
• ?page=2&page_size=100：指定第几页，以及每页的记录数。
• ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
• ?project_type_id=1：指定筛选条件

6. 状态码

服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)

• 200 OK - [GET]：服务器成功返回用户请求的数据
• 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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

7. 错误处理

如果状态码是4xx ,服务器应该向客户端返回错误信息,返回的Key为error, 出错信息作为Value

{
error: "Invalid API key"
}

8. 返回结果

• 根据客户端不同的请求,服务器向客户端返回的结果也有规范
• 服务器返回的数据格式,应该尽量使用JSON,避免使用XML
  • GET : 返回一个或者多个对象
  • POST : 返回新生成的资源对象
  • PUT : 返回完整的资源对象
  • PATCH : 返回完整的资源对象
  • DELETE : 返回空文档