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

欢迎提出任何意见，不是寻求答案，而是提出有关设计考虑的更多建议？

感谢您花时间阅读此条目！

Answer 1

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

REST架构架构的基础是使用HTTP谓词作为唯一的动词，并且不包括URL中的动词。在你的鞋子里，我会考虑重新修改你的系统以删除动词。如果没有真正知道任何动词的含义，很难提出一个设计，但也许更接近于：

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

等等。这是一种更加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从同一文档中取回所有返回的项目。

希望那里有一些值得思考的东西。如果不更详细地了解您的业务需求，任何人都无法告诉您“正确”的事情。

Answer 2

＆＃34; Restful Objects＆＃34;，定义RESTful API，声明操作有效。

可以发现，启用/禁用可用操作，并且可以提供已禁用的原因＆＃39;反馈

行动被调用＆＃39;使用GET（查询），PUT（幂等）或POST（非幂等）

Restful Object Spec（第C-125页）

Answer 3

简短答案：

使用网址末尾的操作来更改状态。

Github这样做是为了激发要点 ： PUT / gists /：gist_id / star

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

长答案：

您的目标是使您的应用程序轻松使用直观。您的用户应以最简单的方式使用您的应用。您的用户不应受到所用技术的限制或严格指导。

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

但是您可以结合使用REST和URI的优点。

记住：

技术应该为您服务，而不是您为技术服务。

如果您成为技术的奴隶，您将最终创建无法使用的应用程序或使用诸如XML或Java Home and Remote接口之类的丑陋技术，因此最终需要编写5个文件来创建一个hello world应用程序。

注意“发光物体综合症”。谷歌一下。

不是因为一项技术是新技术还是“新的做事方式”，而是意味着这是一项好技术，否则您就需要分心，而抛开所有其他技术以屈服于REST。

从技术中获取所需的东西，然后使技术为您服务。

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

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

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

3 个答案: