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

Question

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

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

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

- janetsmith

---

“将POST映射到动作“发送”并不直观”，那么你会映射什么呢？ - Tadeck

通常情况下，“POST”用于创建新实例。如果有多个操作（“立即发送”，“发送”或其他操作类型），我们就会用尽HTTP动词。 - janetsmith

不，我们不是。如果简单的资源还不够，就使用控制器。我建议阅读http://shop.oreilly.com/product/0636920021575.do。至于您的问题，您可以先添加一个资源，然后通过一些控制器发送它。 - Tadeck

Answer 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设计规范书

- Tadeck

---

我认为 REST API 不应该有“动词”，只应该包含“名词”。在我看来，REST API 仅限于表示对象，而不是行为。 - janetsmith

@janetsmith：请不要重复造轮子，“动词”在HTTP中已经存在很长时间了。如果您指的是URI而不是动词，那么客户端使用什么字符串应该与其无关（计算机是否真的有“/email/{id}/sendingQueue”而不是“/email/{id}/send”的偏好？）。控制器是面向函数的资源类型，如果您坚持使用更“静态”的资源类型，则实际上无法执行某些操作。我理解得对吗，您的反对意见是关于控制器的使用？ - Tadeck

是的，我指的是URL命名。在URL中使用“动词”似乎是SOA风格，而REST API是ROA（面向资源的架构）风格。然而，您的“控制器”风格使其更容易映射到我的程序，因为它看起来像面向对象的风格。 - janetsmith

另一种方法可能是将电子邮件ID POST到/queue资源。队列可以接受优先级值以确定电子邮件在队列中的位置。此外，您如何存储电子邮件的状态或状态？如果电子邮件对象中有状态值，则队列控制器可以在发送完成后对/email资源进行PATCH操作。 - Acyra

@AndersÖstman：不，它将成为一个_集合_。在创建资源实例时，会有对API客户端不可见的副作用。这就是全部，简单明了。 - Tadeck