REST 操作和 URL API 设计注意事项

Question

我正在构建一个库存管理系统，并且忙于设计（思考）API 和我的 REST 实现。

我有以下资源，您可以在该资源上执行许多操作/操作。 每个操作都会修改资源，在某些情况下会创建新资源，还会创建历史记录或事务。

我正在寻找有关 URL 和资源设计的可用性和可接受性的专家意见。陷阱和现实世界的例子，欢迎任何意见或批评。

我担心整个应用程序可能是围绕这一大资源开发的？ 我的后端堆栈将是 C# 和 servicestack 框架，而对于前端我将使用 HTML 和 AngularJS。并不是说它有什么不同。

场景 1。 典型的操作是：

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /inventory/{id}/pick
PUT  /inventory/{id}/receive
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /inventory/{id}/transfer
POST /inventory/{id}/return
POST /inventory/{id}/adjustment


{
  "userID": "",       //who is doing the actions (all)
  "tolocationID": "", //new location for inventory (move/takeon/pick/receive/transfer/return)
  "qty": "",          //qty (pick/receive/takeon/transfer/return)
  "comment": "",      //optional for transaction (all)
  "serial": "",       //(takeon/receive)
  "batch": "",        //(takeon/receive)
  "expirydate": "",   //(takeon/receive)
  "itemCode": "",     //(takeon/receive)
  "documentID": "",   //(pick/receive/return/transfer)
  "reference" :"",    //(all)
  "UOM" :"",          //(all)
  "reference" :"",    //(all)
}

这在标准方面是否可以接受。 另一种方法可能是。

场景 2。

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /document/{id}/pick     //**document**
PUT  /document/{id}/receive  //**document**
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /document/{id}/transfer  //**document**
POST /document/{id}/return    //**document**
POST /inventory/{id}/adjustment

然后去改变资源。

场景 3. 在我看来是错误的

POST /transaction/move/{...}
POST /transaction/scrap/{...}
PUT  /transaction/takeon/{...}
POST /transaction/pick/{...}  
PUT  /transaction/receive/{...} 
POST /transaction/hold/{...}
POST /transaction/release/{...}
POST /transaction/transfer/{...}  
POST /transaction/return/{...}
POST /transaction/adjustment/{...}

欢迎任何 cmets，不是在寻找答案，而是在设计考虑方面提供更多建议？

感谢您花时间阅读这篇文章！

Answer 1

我对以下示例的考虑：

POST /inventory/{id}/move

1. “move”一词可以看作是“move-request”的缩写。
2. 在这种情况下，用户发布请求以移动库存。
3. 请求被接受后，会触发相应的服务器动作。
4. 请求是某种资源，它甚至可以被服务器持久化以用于历史记录或如果不立即执行则触发异步任务。

这些是我认为动词可以用在 URI 末尾而不违反任何 REST 准则的主要原因。

其他注意事项：

1. 确保仅在没有可发布或放置的简单资源的情况下使用此“请求抽象”。
2. PUT inventory/{id}/manager 是比 POST inventory/{id}/set-manager 更好的方法，除非您的请求需要一些不是经理属性的参数。
3. 如果您的参数不适合实体/值对象属性，建议使用POST inventory/{id}/manager-update，这显然是一种资源。

最后...大多数 REST 指南示例仅涵盖 CRUD 应用程序。更丰富的领域需要更具表现力的抽象，而不仅仅是使用来自领域实体或值对象的简单名词。

Answer 2

简答：

使用 URL 末尾的动作来改变状态。

Github 这样做是为了给要点加星标： PUT /gists/:gist_id/star

在这里解释 https://developer.github.com/v3/gists/#star-a-gist

长答案：

您的目标是让您的应用程序使用起来毫不费力。您的用户应该以最简单的方式使用您的应用程序。您的用户不应受到您使用的技术的限制或硬性指导。

所以操作和操作本质上不是资源，而是对资源的操作。所以他们不会像 REST 那样响应“资源到 URI 映射”。

但是您可以使用最好的 REST，并且仍然可以使用最好的 URI，将两者结合起来。

记住：

技术应该为你工作，而不是你为技术工作。

如果你成为技术的奴隶，你最终会创建无法使用的应用程序或使用 XML 或 Java Home 和 Remote 接口等丑陋技术，因此你最终会编写 5 个文件来创建一个 hello world 应用程序。

当心“闪亮物体综合症”。去谷歌上查询。

并不是因为一项技术是新的或者是“新的做事方式”，而是意味着这是一项很好的技术，或者你需要分心并抛开所有其他技术来屈服于 REST。

从技术中获取你需要的东西，然后让技术为你工作。

使用 REST api 并不意味着您需要放弃 URL 和 URI 技术的能力。

参考资料： https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful

Answer 3

“Restful Objects”，它定义了一个 RESTful API，声明动作是有效的。

可以发现、启用/禁用可用操作，并且可以给出“禁用原因”反馈。

使用 GET（查询）、PUT（幂等）或 POST（非幂等）“调用”操作

Restful Object Spec（C-125 页）

Answer 4

我有以下资源和你可以执行的资源 许多动作/操作。每个操作都会修改资源和 在某些情况下，创建新资源并创建历史或 交易。

REST 架构模式的基础是使用 HTTP 动词作为唯一动词，而不是在 URL 中包含动词。在您的情况下，我会考虑重新设计您的系统以删除动词。如果不知道任何动词的含义，就很难提出设计建议，但也许更接近：

GET /inventory/{id}
PUT /inventory/{id} -- update with new location 
PUT /inventory/{id} -- update with new status (scrapped)

etc .. 这是一种更 RESTful 的方法。其中许多操作看起来实际上只是更新资源的多个属性的 PUT，例如位置、数量、评论字段等。也许 scrap 是 DELETE？很难说。

另一种选择是使用 POST，其中正文包含有关如何操作库存项目的说明：

POST /inventory-transactions/{id}
{
    "action": "takeon",
    "newLocationId": 12345,
    ...
}

这为您提供了很多可追溯性，因为现在每个操作都可以作为资源进行跟踪。缺点是端点周围有很多复杂性。

您还可以将一些“动词”操作分解为资源：

POST /returned-inventory
{
    "inventoryId": 12345,
    "documentId": 67890,
    "comment": "Busted up",
    ...
}

这让您可以轻松地按状态查看库存项目，这可能有用，也可能没有帮助。例如，您可以调用 GET /returned-inventory?documentId=67890 以从同一个文档中取回所有返回的项目。

希望里面有一些值得深思的地方。如果不更详细地了解您的业务需求，任何人都不可能告诉您“正确”的做法。