REST 操作和 URL API 设计注意事项 [英] REST actions and URL API design considerations

问题描述

我正在构建一个库存管理系统，我正在忙着设计(思考)API 和我的 REST 实现.

I'm building a inventory management system and I'm busy designing (thinking) of the API and my REST implementation.

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

I have the following resources and on the resource you can perform many actions/operations. Each operation will modify the resource and in some cases create a new resource and also create history or transactions.

我正在寻求专家在 URL 和资源设计方面的可用性和可接受性方面的一些意见.陷阱和现实世界的例子，欢迎提出任何意见或批评.

I'm looking for some input from experts in regards to useability and acceptability in regards to URL and resource design. The gotchas and real world examples, any opinion or criticism welcome.

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

My concerns are that the whole application might be develop around this one big resource? My backend stack will be C# and servicestack framework and for frontend I'll be using HTML and AngularJS. Not that it makes a difference.

场景一.典型的操作是:

Scenario 1. Typical operation will be:

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)
}

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

Is this acceptable in regards to standards. The other approach might be.

场景 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. 在我看来是错误的

Scenario 3. in my opinion wrong

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/{...}

欢迎提出任何意见，不是寻找答案而是更多关于设计注意事项的建议?

Any comments welcome, not looking for answer but more advice on design considerations?

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

Thanks for taking the time reading this entry!

推荐答案

我有以下资源，您可以在这些资源上执行许多动作/操作.每个操作都会修改资源和在某些情况下，创建一个新资源并创建历史记录或交易.

I have the following resources and on the resource you can perform many actions/operations. Each operation will modify the resource and in some cases create a new resource and also create history or transactions.

REST 架构模式的基础是使用 HTTP 动词作为唯一动词，而不是在您的 URL 中包含动词.在您看来，我会考虑重新设计您的系统以删除动词.在不真正了解任何动词的含义的情况下很难提出设计建议，但也许更接近于:

Fundamental to the REST architectural schema is the idea of using the HTTP verbs as the only verb, and not including verbs in your URLs. In your shoes, I would consider reworking your system to remove the verbs. It's hard to suggest a design without actually knowing what any of the verbs mean, but perhaps something closer to:

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

etc .. 那是一种更 RESTful 的方法.许多这些操作看起来就像它们真的只是更新资源的多个属性的 PUT，例如位置、数量、评论字段等.也许 scrap 是 DELETE?很难说.

etc .. That's a more RESTful approach. Many of these actions look like they're really just PUTs that update multiple properties of the resource, such as location, quantity, comment field, etc. And perhaps scrap is DELETE? Hard to tell.

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

Another option would be to use POST, where the body includes the instructions for how to operate on the inventory item:

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

这为您提供了很多可追溯性，因为现在每个操作都可以作为资源进行跟踪.不利的一面是端点周围的很多复杂性.

This gives you a lot of traceability, because every operation can now be tracked as a resource. The down side is a lot of complexity around the endpoint.

您还可以将一些动词"操作分解为资源:

You can also break out some of the "verb" operations into resources:

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

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

This lets you easily look at inventory items by their status, which may or may not be helpful. You could, for instance, call GET /returned-inventory?documentId=67890 to get back all the returned items from the same document.

希望里面有一些值得思考的东西.如果不更详细地了解您的业务需求，那么任何人都不可能告诉您正确"的做法.

Hopefully there's some food for thought in there. It's really not going to be possible for anybody to tell you the "right" thing to do without knowing your business requirements in greater detail.

这篇关于REST 操作和 URL API 设计注意事项的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！