Django REST Framework——1. API和RESTful接口规范

一、Web架构

1.1 前后端混合架构（前后端不分离）

先看看请求-响应过程，在收到浏览器的请求时：

1. 服务端将HTML代码与数据、静态资源等在服务端拼接好，一次性将所有内容返回给浏览器；

2. 浏览器只需要将内容呈现给用户即可。

   

开发过程中：等前端开发好HTML页面后，后端开发者就需要对页面的部分内容进行修改，将动态内容放进去，以便后续请求到来时进行渲染及返回。

1.2 前后端分离架构

前后端分离是目前热门的开发方式，大部分互联网都会采用前后端分离的方式开发！

同样先看请求-响应过程，在收到浏览器的请求时：

1. 服务端只将HTML和JavaScript代码返回；

2. 然后浏览器执行js代码，按照事先约定好的API，由Ajax发送请求，以获取所需要的数据或静态资源；

3. 服务端收到Ajax请求，计算后返回请求的数据，或者返回静态资源的地址。这些一般都是以JSON格式返回；

4. 浏览器收到JSON数据，由Ajax按照JSON中的地址获取静态资源后，渲染数据并展现给客户。

   

开发过程中：前端只需要独立编写浏览器代码，后端也只需要对前端提供统一的API即可，不用再处理HTML页面。

二、API（Application Programming Interface，应用程序编程接口）

API是指某个应用程序封装好的一些函数，是提供给其他应用程序或开发人员使用的。通过API，可以方便的使用的本应用程序的功能，而无需了解本应用程序的内部源码。

Web API是API中的一类，它的功能与广义上的API是一样的，只是它提供给外界的是一些url规则而非函数，包括下面4个部分：

1. url：url链接；
2. 请求方式：get、post、patch、delete等；
3. 请求参数：json或xml格式的key-value类型数据；
4. 响应结果：json或xml格式的key-value类型数据。

三、RESTful接口规范

REST是REpresentational State Transfer（表述性状态转移）的首字母缩写。它是分布式超媒体系统的架构风格，最初由Roy Fielding在2000年的论文中提出。

什么是RESTful：
REST-ful,其中ful代表形容词，如helpful、powerful。这类形容词意为"full of,having the quality of"。多加在名词之后表示“充满…的、易于…、可…的、富有…的、具有…的”的意思，是最常用的形容词后缀，反义词后缀是-less。

RESTful 就代表满足REST原则的

参考自：RESTful API

3.1 什么是RESTful规范

REST指的是一组架构约束条件和原则，通常用于Web服务的开发。它没有提出具体的实现，只是提出了一些指导规范，供我们开发时参考。我们可以按照它的规范来，也可以忽视（不建议）。

如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

3.2 RESTful API 设计指南

1. 安全保障

   为了安全起见，应该使用https协议。

2. 表识API

   用api关键字标识api url，与普通url加以区别。如：

   www.xyz.com/api/xxx/，api.xyz.com/xxx/

3. 版本控制

   在url中添加版本版本，或者将版本信息放在请求头中，请求同一资源的不同版本。如：

   api.xyz.com/v1/xxx，Accept: application/vnd.xyz+json;version=1.0。

4. 路径

   数据即是资源，应当使用名词（可用复数形式）。如：www.xyz.com/book/。

5. HTTP动词，即请求方法（method）

   对资源的操作由请求方式决定！

   HTTP请求方法	资源操作	幂等	安全
   GET	从服务器取出资源（一项或多项）	是	是
   POST	在服务器新建一个资源	否	否
   PUT	在服务器更新资源（客户端提供改变后的完整资源）	是	否
   PATCH	与PUT类似，用于更新资源，区别在于PATCH代表部分更新	否	否
   OPTIONS	检测服务器所支持的请求方法，响应头中包含一个名为“Allow”的头，值是所支持的方法，如“GET, POST”。	是	是
   DELETE	DELETE（删除）	是	否

   幂等性：对同一REST接口的多次访问，得到的资源状态是相同的。

   安全性：对该REST接口访问，不会使服务端资源的状态发生改变。

6. 过滤

   通过在url上传递参数的形式提交过滤条件。如：

   https://api.example.com/v1/zoos?limit=10：指定返回记录的数量

   https://api.example.com/v1/zoos?offset=10：指定返回记录的开始位置

   https://api.example.com/v1/zoos?page=2&per_page=100：指定第几页，以及每页的记录数

   https://api.example.com/v1/zoos?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序

   https://api.example.com/v1/zoos?animal_type_id=1：指定筛选条件

7. HTTP状态码

   1xx（信息）：通信传输协议级信息

   1XX系列响应代码仅在与HTTP服务器沟通时使用，平常极少使用。

   2xx（成功）：表示客户端的请求已成功接受

   • 200（OK）：表示REST API成功执行了客户端请求的任何操作；

   • 201（ Created）：用户新建资源成功。

   • 202（Accpted）：已经接受请求并加入了处理队列，但处理尚未完成。

   • 204（No Content）：服务器成功处理，但没有内容可返回。常用于PUT、POST或者DELETE请求的响应。

     204响应绝不能包含消息体，因此总是在头字段之后的第一个空行终止。

   3xx（重定向 ）：表示客户端必须执行一些其他操作才能完成其请求

   • 301（Moved Permanently）：请求的URL已永久移走，并设计了新的URL，客户端应该使用新的URL。

     REST API应在响应的Location头中指定新的URL，并且将旧的URL请求都定向到新的URL。

   • 302（Found）：与301类似，但资源只是临时被移动，客户端应继续使用原有URL。

     302 是执行URL重定向的常用方式。

   • 304（Not Modified）：如果客户端在发送GET请求时附上if-Modified-Since报头，并且从报头指定版本开始从未修改过该资源，则说明客户端的缓存资源是最新的， 要求客户端使用缓存以节省资源。

     此状态代码类似于204，响应正文必须为空。

   4xx（客户端错误）：此类错误状态代码指向客户端

   • 400（Bad Request）：这是一个通用的客户端错误状态，表示客户端请求的语法错误，服务器无法理解。

   • 401（Unauthorized）：客户端试图对一个受保护的资源进行操作，却没有提供正确的认证证书（令牌、用户名、密码错误）。

     响应必须包含WWW-Authenticate头字段，其中包含适服务器将接受哪种认证。

   • 403（Forbidden）：与401错误相对，表明客户端的请求是正确的，但用户没有资源的必要权限。

     该响应代码常用于一个资源只允许在特定时间段内访问，或者允许特定IP地址的用户访问的情况。

   • 404（Not Found）：服务器无法根据客户端的请求找到资源（网页）。

   • 405（Method Not Allowd）：客户端尝试使用资源不允许的HTTP方法。比如，一个资源只支持GET方法，但是客户端使用PUT方法访问。

     405响应必须包含Allow标头，该标头列出资源支持的HTTP方法。

   • 406（Not Acceptable）：用户请求的格式不可得。比如用户请求JSON格式，但是只有XML格式。

   5xx（服务器错误）：服务器负责这些错误状态代码

   • 500（Internal Server Error）：这是一个通用的服务器错误响应。对于大多数web框架，如果在执行请求处理代码时遇到了异常，它们就发送此响应代码。

8. 错误处理

   状态码是4xx时，返回错误信息，并以“error”作为key的名称。如：

   {
       "code":1000,
       "error":"错误信息……"
   }
   

9. 返回结果

   针对不同操作，返回结果应遵守不同的规范。

   • GET /collection：返回资源对象的列表（数组）
   • GET /collection/resource：返回单个资源对象
   • POST /collection：返回新生成的资源对象
   • PUT /collection/resource：返回完整的资源对象
   • PATCH /collection/resource：返回完整的资源对象
   • DELETE /collection/resource：返回一个空文档

10. HATEOAS驱动的REST API

    超媒体：指任何内容，但内容中必须包含指向其他形式的媒体（如图

    像，电影和文本）的链接。

    超媒体在本质上和超文本是一样的，只不过管理的对象从单纯的文本升级到了多媒体。

    HATEOAS（超媒体作为应用程序状态的引擎）是REST应用程序体系结构的约束，它使RESTful样式体系结构与大多数其他网络应用程序体系结构保持独特。

    此体系结构样式允许您在响应内容中使用超媒体链接，以便客户端可以通过遍历超媒体链接，获取相关的API，而不必通过文档来寻找下一步操作。这在概念上与通过单击适当的超链接来浏览网页的Web用户相同，以实现最终目标。

    比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。

    {"link":
    {"rel":"collectionhttps://www.example.com/zoos",
          "href":"https://api.example.com/zoos",
      "title":"List of zoos",
          "type":"application/vnd.yourformat+json"
    }
    }
    

    上面的代码中，有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。

​