用于将一种资源转换为另一种资源的REST URL

Question

我正在努力提供适当的REST URL，以将一种资源转换为另一种资源。 API方法不执行任何CRUD操作，而是将一种资源转换/转换为另一种资源。

我有2个资源Workunit和Document。我对这两个资源进行了3次操作

1>将Workunit转换为Document2>将Workunit同步到Document（逻辑与变换不同）3>将Document转换为Workunit

而且我有以下网址

[POST]  api/v1/workunits/transform
[POST]  api/v1/workunits/sync
[POST]  api/v1/documents/transform

这里的问题是操作是REST URL的一部分

有什么建议吗？

Answer 1

这里的问题是操作是REST URL的一部分

这不是问题-客户端不依赖URL的语义，因此您可以使用任何喜欢的拼写； api/v1/4dc233fa-c77c-49d7-b7d6-296ffeb89612非常令人满意。

类似于将动词用作变量名-可能与您的本地编码标准不符，但是编译器不在乎。您的URL和使用它的通用组件也是如此。

选择一个好的标识符就像选择一个好的名字；它需要对事物是什么有一个清晰的了解。在URI / URL的情况下，被标识的事物是一种资源，也就是说由文档描述的事物。 GET / POST / PUT / DELETE等等都是我们对基础文档做一些有趣的请求。

因此，通常的模式可能是将transform消息发布到工作单元资源，或者将transform消息发布到文档资源，或者将同步消息发布到工作单元资源。

嗯，最后一个听起来向后；如果工作单元未更改，并且文档已通过同步更改，则您可能会将同步消息发送到文档资源。

因此，如果我有/ api / v1 / documents / 1，并且需要对其进行同步，那么我通常会使用POST /api/v1/documents/1，并使用消息正文中描述的同步语义（在网络上，通常是application/x-www-form-urlencoded表示同步消息。

但是它很容易成为一条消息，说“将文档/ 1与工作项/ 2同步”，我POST到同步器的待办事项列表。

我们只是putting documents politely into the server's in-tray，因此它可以做有用的工作。托盘中可以有您想要的任何标签。

Answer 2

在特定情况下很好。

尽管如此，如果我说对了，创建两个不同的控制器可能是个好主意。

由您决定，但要稍微改变一下结构：

将Transformation和Sync的逻辑分为两个不同的控制器，因此可以避免URL问题。

• TransformationController

  [Route("api/v1/transformation-controller/")]
  TransformationController : ControllerBase
  {
       [HttpPost("workunits")]
       public Task<Response> TransformWorkunits()
       {
            //logic
       }
  
       [HttpPost("documents")]
       public Task<Response> TransformDocuments()
       {
            //logic
       }
  }
  

• SynchronizationController

  [Route("api/v1/synchronization-controller/")]
  TransformationController : ControllerBase
  {
       [HttpPost("workunits")]
       public Task<Response> SyncWorkunits()
       {
            //logic
       }
  }
  

因此URL将是：

• [POST] api/v1/transformation-controller/workunits
• [POST] api/v1/synchronization-controller/workunits
• [POST] api/v1/transformation-controller/documents

因此，这是避免动词并适合REST规则的方法。

如果有更多的对象要来回变换/同步，那么您将必须改进这种方法。