如何为电子邮件发送服务设计 REST API？答案

【问题标题】：How to design REST API for email sending service?如何为电子邮件发送服务设计 REST API？
【发布时间】：2012-09-07 01:04:30
【问题描述】：

如何使用 POST、GET、PUT、DELETE 为电子邮件发送服务设计 REST API？

send: POST - /email
retrieve: GET - /email/{id}
delete: DELETE - /email/{id}

这是设计 REST API 的正确方法吗？我觉得将 POST 映射到“发送”操作并不直观。

【问题讨论】：

"将 POST 映射到动作 "send"" 不直观？那么你会映射什么呢？
通常“POST”用于创建新实例。如果有多个操作（“立即发送”、“发送”或其他操作类型），我们将用完 HTTP 动词。
不，我们不是。如果简单的资源还不够，请使用控制器。我推荐阅读shop.oreilly.com/product/0636920021575.do。就您的问题而言，您可以先添加一个资源，然后使用某个控制器发送它。

标签： rest

【解决方案1】：

你给出的方案是正确的。或者，您可以使用控制器来执行一些更复杂的操作。

在您的情况下，它可能如下所示：

(action)           (verb)   (URI)                             (type)
create:            POST   - /emails                         - collection
retrieve:          GET    - /email/{id}                     - resource
update:            PUT    - /email/{id}                     - resource
delete:            DELETE - /email/{id}                     - resource
send immediately:  POST   - /email/{id}/sendImmediately     - controller
just send:         POST   - /email/{id}/send                - controller
do something else: POST   - /email/{id}/someOtherActionType - controller

注意新控制器和更改创建工作。后者相当主观，但合理（因为您无法真正访问“没有实际电子邮件”的 URL，就像我在没有“{id}”部分的情况下解释“/email”一样）。

其他资源：

REST API Design Rulebook

【讨论】：

我认为 REST API 中不应该有“动词”？ IMO REST API 应该只包含“名词”。
@janetsmith：请不要重新发明轮子，“动词”在 HTTP 中已经存在很长时间了。如果您指的是URI，而不是动词，那么它应该与客户端使用的字符串无关（计算机偏好“/email/{id}/sendingQueue”而不是“/email/{id}/send”真的合理吗？ ?)。控制器是面向功能的资源类型，如果您坚持使用更多“静态”类型的资源，您实际上无法执行某些操作。我是否理解正确，您的反对意见是关于控制器的使用？
是的。我指的是 URL 命名。在 URL 中使用“动词”似乎是 SOA 风格，而 REST api 是 ROA（面向资源的架构）风格。但是，您的“控制器”样式更容易映射到我的程序，因为它看起来像面向对象的样式。
@janetsmith：我认为“没有动词，只有名词”是过于简化的方法，可能是为了教人们 REST。这个想法确实是使用您可以轻松编辑并且在集合中聚合的文档（一种资源）（这也是一种资源）。但是要拥有更高级的函数式特性，您需要控制器（另一种资源）。更不用说例如。 Ruby on Rails 在 URL 中使用动词，但它们以 RESTful (see here) 为荣。在 URL 字符串中使用动词并不会降低您的 RESTful。
@AndersÖstman：不，应该是一个集合。创建资源实例时，会有一个 API 客户端看不到的副作用。就是这样，简单明了。