RESTful Web Services教程：什么是REST API及示例

RESTful 关键要素

自问世以来，RESTful Web 服务已取得了长足的进步。2002 年，Web 联盟发布了 WSDL 和 SOAP Web 服务的定义。这形成了 Web 服务实现方式的标准。

2004 年，Web 联盟还发布了另一个名为 RESTful 的标准定义。在过去的几年里，这个标准变得相当流行。并且被世界上许多流行的网站使用，包括 Facebook 和 Twitter。

REST 是一种访问特定环境中资源的途径。例如，您可能有一个服务器可以托管重要的文档、图片或视频。所有这些都是资源的示例。如果一个客户端，例如 Web 浏览器需要其中任何一个资源，它必须向服务器发送一个请求来访问这些资源。现在 REST 服务定义了如何访问这些资源的方式。

RESTful 实现的关键要素如下：

1. 资源 – 第一个关键要素是资源本身。假设服务器上的一个 Web 应用程序包含多个员工记录。假设 Web 应用程序的 URL 是 https://demo.guru99.com。现在，为了通过 REST 服务访问员工记录资源，可以发出命令 https://demo.guru99.com/employee/1 – 这个命令告诉 Web 服务器请提供员工编号为 1 的员工的详细信息。
2. 请求动词 – 这些描述了您想对资源做什么。浏览器发出 GET 动词来指示端点它想要获取数据。但是，还有许多其他动词可用，包括 POST、PUT 和 DELETE 等。因此，在本例 https://demo.guru99.com/employee/1 中，Web 浏览器实际上发出的是 GET 动词，因为它想获取员工记录的详细信息。
3. 请求头 – 这些是与请求一起发送的附加指令。它们可能定义所需的响应类型或授权详细信息。
4. 请求正文 – 数据随请求一起发送。当向 REST web service 发送 POST 请求时，数据通常会发送在请求中。在 POST 调用中，客户端实际上告诉 REST web service 它想要向服务器添加一个资源。因此，请求正文将包含需要添加到服务器的资源的详细信息。
5. 响应正文 – 这是响应的主体。因此，在我们上面的 RESTful API 示例中，如果我们通过请求 https://demo.guru99.com/employee/1 查询 Web 服务器，Web 服务器可能会返回一个 XML 文档，其中包含响应正文中的所有员工详细信息。
6. 响应状态码 – 这些代码是与 Web 服务器的响应一起返回的通用代码。一个例子是 200 代码，当响应客户端时没有错误时通常会返回此代码。

Restful 方法

下图展示了大多数动词（POST、GET、PUT 和 DELETE）以及它们含义的 REST API 示例。

假设我们在该位置定义了一个 RESTful web service。https://demo.guru99.com/employee。当客户端向此 web service 发出任何请求时，它可以指定任何常规的 HTTP 动词 GET、POST、DELETE 和 PUT。以下是客户端发送相应动词时会发生的情况。

1. POST – 这将用于使用 RESTful web service 创建新员工
2. GET – 这将用于使用 RESTful web service 获取所有员工的列表
3. PUT – 这将用于使用 RESTful web service 更新所有员工
4. DELETE – 这将用于使用 RESTful 服务删除所有员工

让我们从单个记录的角度来看。假设有一个员工记录，员工编号为 1。

以下操作将具有相应的含义。

1. POST – 这将不适用，因为我们正在获取员工 1 的数据，而该员工已创建。
2. GET – 这将用于使用 RESTful web service 获取员工编号为 1 的员工的详细信息
3. PUT – 这将用于使用 RESTful web service 更新员工编号为 1 的员工的详细信息
4. DELETE – 用于删除员工编号为 1 的员工的详细信息

为何选择 Restful

Restful 之所以流行，主要是由于以下原因：

1. 异构语言和环境 – 这是根本原因之一，与我们对 SOAP 的看法相同。

• 它使使用各种编程语言构建的 Web 应用程序能够相互通信。
• 借助 Restful 服务，这些 Web 应用程序可以驻留在不同的环境中，有些可能在 Windows 上，而另一些可能在 Linux 上。

但最终，无论环境如何，最终结果都应该是它们能够相互通信。Restful web services 为使用各种编程语言和平台构建的应用程序提供了这种灵活性，使它们能够相互通信。

下图展示了一个 Web 应用程序，该应用程序需要与 Facebook、Twitter 和 Google 等其他应用程序进行通信。

现在，如果客户端应用程序需要与 Facebook、Twitter 等网站配合使用，它们可能不得不了解 Facebook、Google 和 Twitter 是用什么语言构建的，以及它们是在什么平台上构建的。

基于此，我们可以为我们的 Web 应用程序编写接口代码，但这可能会很麻烦。

Facebook、Twitter 和 Google 以 RESTful web services 的形式公开其功能。这允许任何客户端应用程序通过 REST 调用这些 web services。

2. 设备出现 – 如今，一切都需要在移动设备上运行，无论是移动设备、笔记本电脑，甚至是汽车系统。

你能想象一下，要为这些设备上的应用程序编写代码来与普通的 Web 应用程序通信，需要付出多少努力？同样，Restful API 可以使这项工作更简单，因为如第一点所述，您实际上不需要知道设备的底层是什么。

3. 最后是云计算的出现 – 一切都在向云计算迁移。应用程序正逐渐迁移到基于云的系统，例如 Azure 或 Amazon。Azure 和 Amazon 提供了许多基于 RESTful 架构的 API。因此，现在需要以某种方式开发应用程序，使其与云兼容。由于所有基于云的架构都遵循 REST 原则，因此将 Web 服务编程为基于 REST 服务的架构，以便充分利用基于云的服务，这是更有意义的。

Restful 架构

被认为是 RESTful 或 REST 风格的应用程序或架构具有以下特征：

1. 状态和功能被划分为分布式资源 – 这意味着每个资源都应该可以通过常规的 HTTP 命令 GET、POST、PUT 或 DELETE 进行访问。因此，如果有人想从服务器获取文件，他们应该能够发出 GET 请求并获取文件。如果他们想将文件放到服务器上，他们应该能够发出 POST 或 PUT 请求。最后，如果他们想从服务器删除文件，可以发出 DELETE 请求。

2. 架构是客户端/服务器、无状态、分层并支持缓存。

• 客户端-服务器是典型的架构，其中服务器可以是托管应用程序的 Web 服务器，而客户端可以简单到只是 Web 浏览器。
• 无状态意味着 REST 不维护应用程序的状态。例如，如果您使用 DELETE 命令从服务器删除资源，您不能期望该删除信息会传递到下一个请求。

为了确保资源已被删除，您需要发出 GET 请求。GET 请求将用于首先获取服务器上的所有资源。之后，您需要查看资源是否已被实际删除。

RESTful 原则和约束

REST 架构基于一些特征，这些特征将在下面详细介绍。任何 RESTful web service 都必须遵守以下特征才能被称为 RESTful。这些特征也被称为使用 RESTful 基于的服务时需要遵循的设计原则。

1. RESTful 客户端-服务器

   

这是 REST 基于架构最基本的要求。这意味着服务器将有一个 RESTful web service，它将为客户端提供所需的功能。客户端向服务器上的 web service 发送请求。服务器将拒绝请求或满足请求并向客户端提供充分的响应。

2. 无状态

无状态的概念意味着由客户端负责确保所有必需的信息都提供给服务器。这是必需的，以便服务器能够适当地处理响应。服务器不应在客户端的请求之间维护任何信息。这是一个非常简单的独立的问答序列。客户端提出问题，服务器适当地回答。客户端将提出另一个问题。服务器不会记住先前问答场景，并且需要独立回答新问题。

3. 缓存

缓存概念是为了解决上一点所述的无状态问题。由于每个服务器客户端请求都是独立的，有时客户端可能会再次向服务器请求相同的请求。即使它以前已经请求过。此请求将发送到服务器，服务器将给出响应。这会增加网络流量。缓存是客户端上实现的一个概念，用于存储已经发送到服务器的请求。因此，如果客户端给出相同的请求，它将不是去服务器，而是去缓存获取所需信息。这节省了从客户端到服务器的网络往返流量。

4. 分层系统

分层系统的概念是，任何额外的层（如中间件层）都可以插入到客户端和托管 RESTFul web service 的实际服务器之间（中间件层是创建所有业务逻辑的地方。这可以是与客户端交互的额外服务，然后再调用 web service）。但引入这一层需要是透明的，以免干扰客户端和服务器之间的交互。

5. 接口/统一契约

这是 RESTful web services 应如何工作的底层技术。RESTful 主要基于 HTTP Web 层，并使用以下关键动词与服务器上的资源进行交互：

• POST – 在服务器上创建资源
• GET – 从服务器检索资源
• PUT – 更改资源状态或更新它
• DELETE – 从服务器删除或移除资源

在 ASP.NET 中创建您的第一个 Restful web service

在本 REST API 教程中，我们将学习如何在 ASP.NET 中创建 Restful web service。

Web 服务可以用多种语言创建。可以使用许多集成开发环境来创建基于 REST 的服务。

在本 RESTful API 示例中，我们将使用 Visual Studio 在 .Net 中创建我们的 REST 应用程序。在我们的示例中，对于 Restful web services，我们将模拟以下 REST 服务示例。

我们将有一个 Restful web service，它将处理以下数据集。

以下数据集代表了一个 REST API 示例，该示例有一个公司，它根据 Tutorialid 公开其拥有的教程。

Tutorialid	TutorialName
0	数组
1	队列
2	堆栈

在我们的 REST API 教程示例中，我们将实现以下 Restful Verbs。

1. GET Tutorial – 当客户端调用此 Restful API 时，它们将获得 Web 服务提供的所有可用教程。
2. GET Tutorial/Tutorialid – 当客户端调用此 Restful API 时，它们将根据客户端发送的 Tutorialid 获取教程名称。
3. POST Tutorial/Tutorialname – 当客户端调用此 Restful API 时，客户端将提交一个请求来插入一个 Tutorialname。然后，Web 服务会将提交的 Tutorial 名称添加到集合中。
4. DELETE Tutorial/Tutorialid – 当客户端调用此 Restful API 时，客户端将提交一个请求，根据 Tutorialid 删除一个 Tutorialname。然后，Web 服务会将提交的 Tutorial 名称从集合中删除。

在本 RESTful API 教程中，请遵循以下步骤来创建我们的第一个 RESTful web services，它执行上述实现。

如何创建您的第一个 Restful Web Service

步骤 1) 创建新项目。
第一步是创建一个空的 Asp.Net Web 应用程序。在 Visual Studio 2013 中，单击菜单选项 文件->新建项目。

单击“新建项目”选项后，Visual Studio 将为您提供另一个对话框，用于选择项目类型并提供项目的必要详细信息。这将在本 RESTful API 教程的下一步中进行说明。

步骤 2) 输入项目名称和位置。

1. 确保首先选择 ASP.NET Web 应用程序的 RESTful web services C# Web 模板。项目必须是此类型才能创建 Web services 项目。通过选择此选项，Visual Studio 将执行必要步骤，添加任何基于 Web 的应用程序所需的必需文件。
2. 为您的项目命名，在本例中我们将其命名为“Webservice.REST”。
3. 然后确保提供项目文件将存储的位置。

完成后，您将在Visual Studio 2013的解决方案资源管理器中看到已创建的项目文件。

步骤 3) 创建 Web service 文件。
下一步是创建将包含 RESTful web service 的 Web service 文件。

1. 首先右键单击项目文件，如下图所示

2. 在此步骤中，
   1. 右键单击项目文件
   2. 选择“添加->新项”选项。

在出现的对话框中，您需要执行以下操作：

1. 选择 WCF Service (Ajax-enabled) 选项 – 选择此类型的文件，它会导致 Visual Studio 添加一些基本代码，帮助创建 RESTful web service。WCF 代表 Windows Communication Foundation。WCF 是一个库，用于各种平台或同一平台上的应用程序通过 TCP、HTTP、HTTPS 等各种协议进行通信。Ajax 基本上是异步 JavaScript 和 XML。AJAX 允许 Web 页面通过在后台交换少量数据来异步更新。
2. 接下来为服务命名，在本例中为 TutorialService。
3. 最后，单击“添加”按钮将服务添加到解决方案。

步骤 4) 进行配置。
下一步是实际进行配置更改，以使此项目能够完全与 RESTful web services 配合使用。这需要对名为 Web.config 的文件进行更改。此文件显示在 Webservice 项目文件的同一窗口中。Web.config 文件包含使 Web 应用程序正常运行的所有配置。所做的更改实际上允许应用程序将数据作为纯 RESTful web service 发送和接收。

1. 单击 Web.config 文件以打开代码

2. 查找行 <enableWebScript>

3. 将该行更改为 <webHttp>

步骤 5) 添加我们的实现代码。
本 RESTful API 教程的下一步是添加我们的实现代码。以下所有代码都必须写入 TutorialService.svc 文件中。

1. 第一部分是添加代码来表示我们将要在程序中使用的数据。所以我们将有一系列字符串变量，其值为“Arrays”、“Queues”和“Stacks”。这将代表我们的托管 Web 服务提供的教程名称。

namespace Webservice.REST
{
	[ServiceContract(Namespace = "")]
	[AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed
	public class TutorialService
	{
		private static List<String> lst = new List<String>
		(new String[] {"Arrays","Queues","Stacks"});

步骤 6) 定义 GET 方法的代码。
接下来，我们将定义 GET 方法的代码。此代码也将驻留在同一个 TutorialService.svc 文件中。每当我们从浏览器调用服务时，此代码都会运行。

以下方法将用于满足以下场景：

• 如果用户想要一份所有可用教程的列表，则需要编写以下代码来完成此操作。

[WebGet(UriTemplate="/Tutorial")]

public String GetAllTutorial()
{
	int count = 1st.Count;
	String TutorialList = "";
	for (int i = 0; i < count; i++)
	TutorialList = TutorialList + lst[i] + ",";
	return TutorialList;
}

代码解释：

1. 第一行代码是最重要的。它用于定义我们如何通过 URL 调用此方法。因此，如果我们的 web service 的链接是 https://:52645/TutorialService.svc，如果我们向 URL 追加 ‘/Tutorial’，如 https://:52645/TutorialService.svc/Tutorial，上面的代码将被调用。‘WebGet’ 属性是一个参数，它允许此方法成为 RESTful 方法，以便可以通过 GET 动词调用它。
2. 此代码部分用于遍历‘lst’变量中的字符串列表，并将它们全部返回给调用程序。

步骤 7) 返回输出。
下面的代码确保，如果对 Tutorial Service 进行了 GET 调用，并带有 Tutorial id，它将返回相应的 Tutorial Name，该名称基于 Tutorial id。

[WebGet (UriTemplate = "/Tutorial/{Tutorialid}")]

public String GetTutorialbyID(String Tutorialid)
{
	int pid;
	Int32.TryParse(Tutorialid, out pid);
	return lst[pid];
}

代码解释：

1. 第一行代码是最重要的。它用于定义我们如何通过 URL 调用此方法。因此，如果我们的 web service 的链接是 https://:52645/TutorialService.svc，如果我们向 URL 追加 ‘/Tutorial/{Tutorialid}’，那么我们可以像这样调用 web service：https://:52645/TutorialService.svc/Tutorial/1 作为示例。然后，Web 服务需要返回具有 Tutorial id#1 的 Tutorial 名称。
2. 此代码部分用于返回传递给 web 方法的具有 Tutorial id 的“Tutorial name”。

• 默认情况下，需要记住的是，在浏览器中传递到 URL 的任何内容都是字符串。
• 但您必须记住，我们列表的索引必须是整数，因此我们添加了必要的代码来首先将 Tutorialid 转换为整数，然后使用它来访问我们列表中的索引位置，并且
• 然后相应地将值返回给调用程序。

步骤 8) 编写 POST 方法的代码。
下一步是编写我们的 POST 方法的代码。每当我们想通过 POST 方法向我们的教程列表中添加字符串值时，都将调用此方法。例如，如果您想添加“Software Testing”的教程名称，则需要使用 POST 方法。

代码解释：

1. 第一行是附加到我们方法的 ‘WebInvoke’ 属性。它允许通过 POST 调用调用该方法。RequestFormat 和 ResponseFormat 属性必须指定为 JSON，因为在向 RESTFul web service 提交值时，值必须采用此格式。
2. 第二行代码用于将通过 POST 调用传递的字符串值添加到我们现有的教程字符串列表中。

步骤 9) 添加处理 DELETE 操作的方法。
最后，我们将添加处理 DELETE 操作的方法。每当我们想通过 DELETE 方法从我们的教程列表中删除现有的字符串值时，都将调用此方法。

[WebInvoke(Method = "DELETE", RequestFormat = WebMessageFormat.Json,
	UriTemplate = "/Tutorial/{Tutorialid}", ResponseFormat = WebMessageFormat.Json,
	BodyStyle = WebMessageBodyStyle.Wrapped)]
	
public void DeleteTutorial(String Tutorialid)
{
	int pid;
	Int32.TryParse(Tutorialid, out pid);
	1st.RemoveAt(pid);
}

代码解释：

1. 第一行是附加到我们方法的 ‘WebInvoke’ 属性。它允许通过 POST 调用调用该方法。RequestFormat 和 ResponseFormat 属性必须指定为 JSON，因为在向 RESTFul web service 提交值时，值必须采用此格式。请注意，Method 参数被设置为“DELETE”。这意味着每当我们发出 DELETE 动词时，都会调用此方法。
2. 第二行代码用于获取通过 DELETE 调用发送的 Tutorialid，然后从我们的列表中删除该 id。（代码中的 Int32 函数用于将 Tutorial ID 从字符串变量转换为整数）。

运行您的第一个 Restful web service

现在我们已经在上面的部分创建了整个 web service。让我们看看如何运行 Tutorial 服务，以便可以从任何客户端调用它。

要运行 web service，请按照以下步骤操作：

步骤 1) 右键单击项目文件 – Webservice.REST

步骤 2) 选择菜单选项“设置为启动项目”。这将确保在 Visual Studio 运行整个解决方案时运行此项目。

步骤 3) 下一步是运行项目本身。现在，根据系统上安装的默认浏览器，相应的浏览器名称将出现在 Visual Studio 的运行按钮旁边。在本例中，我们看到 Google Chrome。只需单击此按钮。

输出：-

运行项目时，您可以浏览到您的 TutorialService.svc/Tutorial 部分，您将看到以下输出。

在上图中，

• 您可以看到浏览器正在调用‘GET’动词并执行 web service 中的‘GetAllTutorial’方法。此模块用于显示我们 web service 公开的所有教程。

测试您的第一个 Restful web service

在上图中，我们已经看到了如何使用浏览器执行‘GET’动词并调用‘GetAllTutorial’。

1. 现在，让我们使用浏览器来执行以下用例场景。

GET Tutorial/Tutorialid – 当客户端调用此 Restful API 时，它们将根据客户端发送的 Tutorialid 获取教程名称。

在浏览器中，在 URL 中的 Tutorial 单词后附加字符串 /1。如果您点击 Enter 键，您将看到以下输出。

现在您将看到“Queues”的输出，它实际上对应于我们教程字符串列表中的数字 1。这意味着‘GetTutorialbyID’方法现在正在从我们的 Webservice 调用。它还表明值 1 已通过浏览器成功传递到我们的 web service 和我们的方法，这就是为什么我们在浏览器中获得正确的相应值“Queues”。

2. 接下来，我们通过执行以下场景来消费我们的 web service。为此，您需要安装一个名为“Fiddler”的工具，这是一个可以从该站点免费下载的工具。

POST Tutorial/Tutorialname – 当客户端调用此 Restful API 时，客户端将提交一个请求来插入一个 Tutorialname。然后，Web 服务会将提交的 Tutorial 名称添加到集合中。

运行 Filddler 工具并执行以下步骤；

1. 转到 Composer（作曲家）部分。这用于创建可以提交给任何 Web 应用程序的请求。
2. 确保请求类型为“POST”，并且正在命中正确的 URL，在本例中应该是 https://:52645/TutorialService.svc/Tutorial。
3. 确保 Content-Type 被标记为 application/json。请记住，我们在 Web 服务中的 POST 请求方法仅接受 JSON 样式数据，因此在向我们的应用程序发送请求时，我们需要确保指定此项。
4. 最后，我们需要输入我们的数据。请记住，我们的 POST 方法接受一个名为‘str’的参数。所以我们在这里指定我们想将“Trees”这个值添加到我们教程名称的集合中，并确保它被标记为 str 变量名。

最后，只需单击 Fiddler 中的 Execute（执行）按钮。这将向 Web 服务发送一个请求，将数据“Trees” POST 到我们的 Web 服务。

现在，当我们浏览到 Tutorial URL 以显示我们 Tutorial 列表中的所有字符串时，您将看到“Trees”的值也存在。这表明 POST 请求已成功执行到 Web 服务，并且已成功添加到我们的 Tutorial 列表中。

3. 接下来，我们通过执行以下场景来消费我们的 Web 服务。为此，我们也需要使用 Fiddler 工具。

DELETE Tutorial/Tutorialid- 当客户端调用此 Restful API 时，客户端将提交一个请求，根据 Tutorialid 删除一个 Tutorialname。然后，Web 服务会将提交的 Tutorial 名称从集合中删除。

运行 Filddler 工具并执行以下步骤

1. 转到 Composer（作曲家）部分。这用于创建可以提交给任何 Web 应用程序的请求。
2. 确保请求类型为“DELETE”，并且正在命中正确的 URL，在本例中应该是 https://:52645/TutorialService.svc/Tutorial。确保用于删除列表中字符串的 ID 作为参数通过 URL 发送。在我们上面的 REST 示例中，我们发送的是 1，这将删除我们集合中的第二个元素，即“Queues”。

最后，只需单击 Fiddler 中的 Execute（执行）按钮。这将向 Web 服务发送一个请求，将数据“Queues” DELETE 到我们的 Web 服务。

现在，当我们浏览到 Tutorial URL 以显示我们 Tutorial 列表中的所有字符串时，您会注意到“Queues”的值已不再存在。

这表明 DELETE 请求已成功执行到 Web 服务。我们教程字符串列表中索引号为 1 的元素已成功删除。

摘要

• REST 代表 REpresentational State Transfer。REST 用于构建轻量级、可维护且可扩展的 Web 服务。
• 越来越多的应用程序正在转向 Restful 架构。这是因为现在有很多人使用移动设备，并且有更多种类的应用程序正在迁移到云。
• REST 的主要方面是服务器上驻留的资源以及 GET、POST、PUT 和 DELETE 动词，这些动词可用于处理这些资源。
• Visual Studio 和 .Net 可用于创建 Restful web services。
• 在测试 POST 和 PUT 的 Web 服务时，您需要使用另一个名为 fiddler 的工具，该工具可用于将 POST 和 PUT 请求发送到服务器。