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

问题描述

我建立一个库存管理系统，我的API和我的休息落实忙于设计（思考）。

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

我要找的专家在关于使用性和可接受性的问候一些输入URL和资源的设计。该陷阱和现实世界的例子，任何意见或批评的欢迎。

我的担心是，整个应用程序可能围绕这一大的资源来发展？
我的后端堆栈将是C＃和servicestack框架和前端我将使用HTML和AngularJS。不，它的确与众不同。

方案1。
典型的操作将是：

  POST /存货/ {ID} /移动
POST /存货/ {ID} /废料
PUT /存货/ {ID} / takeon
POST /存货/ {ID} /回暖
PUT /存货/ {ID} /接收
POST /存货/（编号）/持有
POST /存货/ {ID} /释放
POST /存货/ {ID} /传输
POST /存货/ {ID} /回报
POST /存货/（编号）/调整
{
  用户ID：，//是谁做的动作（全部）
  tolocationID：，//库存新的位置（移动/ takeon /拾取/接收/传送/返回）
  数量：，//数量（拾取/接收/ takeon /传输/返回）
  意见：，//可选的交易（全部）
  系列：，//（takeon /接收）
  一批：，//（takeon /接收）
  expirydate：，//（takeon /接收）
  项code：，//（takeon /接收）
  documentID：，//（拾取/接收/返回/传输）
  参考：，//（全部）
  计量单位：，//（全部）
  参考：，//（全部）
}
 

时的问候标准这个可以接受的。
另一种方法可能。

情景2

  POST /存货/ {ID} /移动
POST /存货/ {ID} /废料
PUT /存货/ {ID} / takeon
POST /文件/ {ID} /挑// ** **文件
PUT /文件/ {ID} /接收// ** **文件
POST /存货/（编号）/持有
POST /存货/ {ID} /释放
POST /文件/ {ID} /转让// ** **文件
POST /文件/ {ID} /返回// ** **文件
POST /存货/（编号）/调整
 

和然后改变资源

3，情景在我看来，错

  POST /交易/移动/ {...}
POST /交易/废钢/ {...}
PUT /交易/ takeon / {...}
POST /交易/拾取/ {...}
PUT /交易/接收/ {...}
POST /交易/暂停/ {...}
POST /交易/发行/ {...}
POST /交易/转让/ {...}
POST /交易/返回/ {...}
POST /交易/调整/ {...}
 

任何意见，欢迎，不找在设计方面的答案，但更多的意见？

感谢您抽出宝贵时间阅读此项目！

解决方案

  

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

根本，以REST架构模式是使用HTTP动词作为唯一的动词，而不是包括你的URL动词的想法。在你的鞋，我会考虑重做你的系统中删除动词。很难建议实际上不知道什么任何动词的意思是一家集设计，但也许更接近于：

  GET /存货/ {ID}
PUT /存货/（编号） - 用新的位置更新
PUT /存货/（编号） - 新的状态更新（报废）
 

等等。这是一个更RESTful方法。许多这些行动看起来像他们真的只是把资源的该更新多个属性，如位置，数量，注释字段，等等也许废料被删除？很难说。

另一种选择是使用POST，在身体包括如何在库存项目操作说明：

  POST /库存交易/ {ID}
{
    行动：takeon
    newLocationId：12345，
    ...
}
 

这给你很多的可追溯性，因为每个操作现在可以跟踪作为一种资源。不利的一面是很多复杂的终点左右。

您还可以分解出一些动词的运营到资源：

  POST /返回库存
{
    inventoryId：12345，
    documentId：67890，
    意见：捣毁了
    ...
}
 

这可以让你轻松地查看其状态的库存物品，这可能会或可能不会有帮助。你可以，例如，呼叫 GET /返回库存？documentId = 67890 取回来自同一个文档中的所有返回的项目。

希望有一些食物在那里思考。它真的不会有可能为任何人告诉你正确的事情不知道更详细的业务需求做的。

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.

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.

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.

Scenario 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

and then to change the resources.

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.

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 .. 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.

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",
    ...
}

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屋！