14

我正在尝试使用 ASP.NET Web API 为我们的服务设计一个 RESTful Web API。我在弄清楚如何将非 CRUD 操作路由到正确的控制器操作时遇到了麻烦。假设我的资源是一扇门。我可以用我的门做所有熟悉的 CRUD 事情。假设我的门的模型是：

public class Door
{
   public long Id { get; set; }
   public string InsideRoomName { get; set; }
   public string OutsideRoomName { get; set; }
}

我可以通过我的 web api 完成所有标准的 CRUD 操作：

POST: http://api.contoso.com/v1/doors
GET: http://api.contoso.com/v1/doors
GET: http://api.contoso.com/v1/doors/1234
GET: http://api.contoso.com/v1/doors?InsideRoomName=Cafeteria
PUT: http://api.contoso.com/v1/doors/1234
DELETE: http://api.contoso.com/v1/doors/1234

等等。我遇到麻烦的地方是当我需要对我的门进行非 CRUD 操作建模时。我想对我的资源建模一个 Lock 和 Unlock 动词。阅读ASP.NET 文章，该指南似乎是在使用自定义操作时切换到 RPC 样式调用。这给了我一条路径：

PUT: http://api.contoso.com/v1/doors/1234/lock
PUT: http://api.contoso.com/v1/doors/1234/unlock

这似乎与旨在指示资源的路径的 REST 精神相冲突。我想我可以将动词建模为资源：

POST: http://api.contoso.com/v1/doors/1234/lockrequests
POST: http://api.contoso.com/v1/doors/1234/unlockrequests

在这种情况下，我仍然可以使用推荐的 {controller}/{id}/{action} 但似乎我仍在创建混合 RPC / REST API。就 REST 接口而言，是否有可能，甚至推荐将自定义操作放在参数列表中？

PUT: http://api.contoso.com/v1/doors/1234?lock
PUT: http://api.contoso.com/v1/doors/1234?unlock

我可以预见需要使用查询参数支持此调用，例如：

PUT: http://api.contoso.com/v1/doors?lock&InsideRoomName=Cafeteria

我将如何创建将这个请求映射到我的 DoorsController 的路由？

public class DoorsController : ApiController
{
   public IEnumerable<Doord> Get();
   public Door Get(long id);
   public void Put(long id, Door door);
   public void Post(Door door);
   public void Delete(long id);

   public void Lock(long id);
   public void Unlock(long id);
   public void Lock(string InsideRoomName);
}

关于 REST API 设计方面什么是最佳实践，什么不是最佳实践，我可能在这里做出了一些错误的假设，因此也欢迎任何指导。

4

3 回答 3

6

To handle the lock/unlock scenario you could consider adding a State property to the Door object:

   public State State { get; set; }

where State is an enum of available values, e.g. 

{
LockedFromOutsideRoom,
LockedFromInsideRoom,
Open
}

To clarify: That you're adding a state to the object is not against restful principles as the state is passed over the api every time you make a call to do something with the Door.

Then via the api you would send a PUT/POST request to change the state of the Door on each lock/unlock. Post would probably be better as it's only one property that gets updated:

POST: http://api.contoso.com/v1/doors/1234/state
body: {"State":"LockedFromInsideRoom"}
于 2013-04-18T20:07:43.253 回答
5

从 RESTful 原则来看，也许最好引入一个“状态”属性来管理那些非 CURD 操作。但我认为它不符合真正的生产发展。

对这类问题的每一个答案，看起来您都必须使用变通方法来强制您的 API 设计符合 RESTful。但我担心的是，这真的给用户和开发者都带来了便利吗？

让我们看一下 Google bloger 的 API3.0 设计：https ://developers.google.com/blogger/docs/3.0/reference ，它使用 lot URL 进行非 CURD 操作。

这很有趣，

POST  /blogs/blogId/posts/postId/comments/commentId/spam

描述是

将评论标记为垃圾邮件。这会将评论的状态设置为垃圾邮件，并将其隐藏在默认的评论呈现中。

您可以看到，评论具有指示它是否为垃圾邮件的状态，但它的设计不像 JoannaTurban 上面提到的答案。

我认为从用户的角度来看，它更方便。不需要关心“状态”的结构和枚举值。实际上你可以在“状态”的定义中加入很多属性，比如“isItSpam”、“isItReplied”、“isItPublic”等。如果状态有很多东西，设计就会变得不友好。

在某些业务逻辑要求上，使用易于理解的动词，而不是试图使其完全成为“真正的”RESTful，它对用户和开发人员来说都更有效率。这是我的意见。

于 2016-06-20T09:15:53.503 回答
1

从 REST 的角度来看，您可能希望将锁本身视为一种资源。通过这种方式，您可以独立于门创建和删除锁（尽管可能从门表示中定位锁端点）。资源的 URL 可能与门的 URL 相关，但是从 RESTful 的角度来看，这无关紧要。REST 是关于资源之间的关系，所以重要的部分是锁的 url 可以从门的表示中发现。

于 2013-04-18T20:13:30.730 回答