Web API - REST 帮助和说明

本文关键字：说明 帮助 REST API Web | 更新日期: 2023-09-27 18:35:47

我正在使用WebAPI编写一个API，当我从头开始设计它时，我正在尝试使其RESTful。过去，在做Web服务工作时，我总是使用RPC模式（ASMX，SOAP 等） - 例如。使用与我希望它执行的操作匹配的任意方法名称。对我来说，这似乎比 REST 更直观和明确，但鉴于 WebApi 本质上似乎更 RESTful （我知道你可以改变路线，所以它不是），我决定尝试让它成为 RESTful。

我了解（我认为！）基础知识 - 例如。POST 用于创建，PUT 用于指定 ID 时的更新，GET 用于获取，DELETE 用于删除等。

我的困惑是如何处理返回集合与单个对象。例如，假设我有一个名为 UsersController 的 API 控制器。据我所知，我会有以下 URL：

GET: /api/users (lists all users)
GET: /api/users/1 (lists details about user with ID 1)
POST: /api/users (creates a new user with details sent in the POST data)
PUT: /api/users/1 (updates the existing user with ID 1 with details sent in the POST data)
DELETE: /api/users/1 (deletes the existing user with ID 1)

对于上面的第一个URL，我还需要发送各种过滤器/搜索条件。此条件是否只是作为查询字符串参数传递？还是我应该为此"搜索"功能使用完全不同的控制器？例如。用户搜索控制器？如果是这样，在这种情况下应该是 POST 还是仍然是 GET？实际上，在我写这篇文章的时候，我想知道一个单独的控制器是否有意义，因为我可能希望在 GET 中为单个用户返回比在搜索结果中返回更多详细信息。如果同一个控制器确实为单个对象 GET 与返回集合的 GET 返回不同的数据，它是否使它不是 RESTful？

Web API - REST 帮助和说明

对于上面的第一个URL，我还需要发送各种过滤器/搜索条件。此条件是否只是作为查询字符串参数传递？

使用查询字符串指定筛选器/搜索参数绝对有意义。

我应该为此"搜索"功能使用完全不同的控制器吗？例如。用户搜索控制器？

你不应该那样做。我在这里看到有几个原因：

  1. GET: /api/users中将具有几乎相同的功能

  2. 您可以通过一种方法轻松实现GET: /api/users、GET: /api/users?filter=...&sort=...和GET: /api/users/1：

    //If you are using EF it could look like
//filter and sort arguments could be added here as well
public HttpResponseMessage Get(int? id)  
{
   if(id.HasValue)
   {
       return Request.CreateResponse(
           HttpStatusCode.OK, 
           Context.Users.SingleOrDefault<Users>(u => u.Id == id));              
   }
   var users = Context.Users.Select(apply filter).OrderBy(apply sort).ToList();
   return Request.CreateResponse(HttpStatusCode.OK, users);   
}

你可以看看OData - 它可以帮助你实现。

  1. 在不同的控制器之间传播此逻辑会损害单一责任原则 - 您的用户控制器应处理与用户相关的所有逻辑，并且仅处理此逻辑

如果是这样，在这种情况下应该是 POST 还是仍然是 GET？

如果你想让你的API RESTful，你应该使用GET。但您应该知道，通过 GET 返回 JSON 对象数组可能容易受到 JSON 劫持。此漏洞的最简单解决方案之一是仅允许通过 POST 获取 JSON 数组（还有其他解决方案）。

我可能希望在 GET 中为单个用户返回比搜索结果中返回更多详细信息。如果同一个控制器确实为单个对象 GET 与返回集合的 GET 返回不同的数据，它是否使它不是 RESTful？

返回单个对象比集合更多的详细信息是完全可以的。它不会以任何方式影响 API 的 RESTability。

评论

你写道：

指定 ID 时进行更新的 PUT

实际上这并不完全正确：

  • PUT应用于完全替换整个实体
  • 应使用 PATCH 来执行部分更新。
如果要

将条件作为查询字符串参数传递给 URI，可以使用属性路由到 WebAPI 中执行此操作。我认为 web-api 中的属性路由对您有所帮助。

是的，我会将过滤器参数作为查询字符串选项传递。应用程序的"宁静性"不依赖于控制器结构，因此您可以遵循最适合您的应用程序的结构

相关文章：