投稿
  1. 首页
  2. 随笔

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

投影机幕布 • 2022-12-16 • 随笔 • 阅读 20

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

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

文章目录
  • 一、Web架构
    • 1.1 前后端混合架构（前后端不分离）
    • 1.2 前后端分离架构
  • 二、API（Application Programming Interface，应用程序编程接口）
  • 三、RESTful接口规范
    • 3.1 什么是RESTful规范
    • 3.2 RESTful API 设计指南
      • 安全保障
      • 表识API
      • 版本控制
      • 路径
      • HTTP动词，即请求方法（method）
      • 过滤
      • HTTP状态码
        • 1xx（信息）：通信传输协议级信息
        • 2xx（成功）：表示客户端的请求已成功接受
        • 3xx（重定向 ）：表示客户端必须执行一些其他 *** 作才能完成其请求
        • 4xx（客户端错误）：此类错误状态代码指向客户端
        • 5xx（服务器错误）：服务器负责这些错误状态代码
      • 错误处理
      • 返回结果
      • HATEOAS驱动的REST API

一、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”。是是DELETEDELETE（删除）是否

    幂等性：对同一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表示返回类型。

​

欢迎分享，转载请注明来源：内存溢出

原文地址: http://outofmemory.cn/zaji/5658073.html

赞 (0)
打赏 微信扫一扫 微信扫一扫 支付宝扫一扫 支付宝扫一扫
投影机幕布 投影机幕布 一级用户组
0 0
上一篇 2022-12-16
下一篇 2022-12-16

发表评论

登录后才能评论

评论列表（0条）

保存