HTTP Methods and REST APIsHTTP 方法与 REST API

预计所需时间：30 分钟

目标

阅读本文档后，您应该能够：

• 定义与HTTP方法相关的术语
• 解释编写REST APIs的指南和最佳实践

互联网依赖于客户端-服务器架构。最终用户与客户端进行交互，而服务器则存储操作应用程序、业务逻辑和数据的服务1。客户端与服务器进行通信，以实现最终用户所需的功能。数据通过超文本传输协议进行客户端和服务器之间的传输，更常见的称为HTTP2。这种通信通常通过API3进行。在2000年，开发了一套用于为客户端-服务器架构编写这些API的指南，称为REST4 API。

“REST”的缩写代表表述性状态转移。在更详细地解释这个术语之前，让我们先讨论HTTP方法和一些术语。

在客户端/服务器架构中，应用程序由一个或多个驻留在服务器上的服务组成。这些服务包含资源5。客户端通过使用具有服务内端点9的路由8的请求对象7向资源发出请求6。应用程序向客户端发送响应对象10，以响应11该请求。

请求对象包含三个部分：URL12、请求头13和请求体14。服务器使用URL来识别被操作的服务及其内的端点。URL包含四个部分：协议15、主机名16、路径17和查询字符串18。请求头包含有关请求客户端资源的元数据，例如用户代理19、主机20、内容类型21、内容长度22以及客户端在响应中应期待的数据类型。

服务器以包含头部23、主体24和状态码25的响应对象进行响应。响应对象的主体通常包含一个JSON26 有效负载27，以将数据返回给客户端。

在REST API中，可以使用多种HTTP方法来允许客户端与服务之间的交互。最常用的方法是GET28、POST29、PUT30、DELETE31和PATCH32。

方法的名称描述了当应用该方法时资源会发生什么。如果多次调用相同的API方法，PUT和DELETE方法将产生幂等33的数据。

HTTP有三种传递参数的方式：URL路径参数34、URL查询参数35和头部参数36。路径和查询参数作为URL的一部分传递，而头部参数则由浏览器直接传递给服务。

当服务完成请求时，它会返回响应。HTTP状态码应成为该响应的一部分。HTTP状态码指示响应是否已完成。响应代码类别如下表所示。

如前所述，REST是一组指南。要使API被视为RESTful，必须满足五个要求，以及一个可选标准：

1. API利用由通过HTTP管理和交付的资源组成的客户端-服务器架构。
2. 客户端与服务器之间的通信是无状态37的。
3. 数据是可缓存38的，以提高客户端的性能。
4. 接口以标准格式传输，以便存储在服务器上的请求资源与发送给客户端的表示分开。发送给客户端的表示包含足够的数据，以便客户端可以操作该表示。
5. 请求和响应通过不同的层进行通信，例如中间件39。客户端和服务器通常不会直接相互通信。
6. （可选）资源通常是静态的，但也可以包含可执行代码。代码应仅在客户端请求时执行。

当客户端发出请求时，它还必须将其状态信息传递给服务器。客户端与服务器之间的每次通信都应包含执行请求所需的所有信息。客户端而不是服务维护状态。每个请求必须包含必要的信息，以便服务器理解请求。因此，例如，如果用户正在查看数据库记录并且该记录需要更新，客户端还必须发送需要更新的记录。服务器不知道当前正在查看哪条记录。

在定义RESTful服务时使用@app.route()方法。该方法接受两个参数：从URL到被操作服务的路由，以及一个可选的HTTP方法参数，例如POST、GET等。路由参数可以包括变量，例如<username>。路由的根由/表示。例如，如果您希望路由为www.mywebsite.com/accounts，则只需在@app.route()函数中指定/accounts作为路由参数。

REST API具有以下特征：

• 基于资源；也就是说，它们描述一组资源
• 仅包含名词，而不包含动词
• 当提到单个资源时使用单数名词，提到资源集合时使用复数名词
• 始终通过URL进行标识

URL格式指南

• 应使用斜杠/表示目录结构中的层次关系
• 应避免使用尾随斜杠，例如/resource/
• 应使用连字符，而不是驼峰式，例如/my-resource，而不是/myResource
• 应不在URL中使用下划线_，例如/my-resource，而不是/my_resource
• 应使用小写字母
• 应不在URL中使用句点.
• URL中可以包含多个从属资源和ID，例如GET /resource/{id}/subordinate/{id}

术语和定义