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

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

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

Answer 1

简短回答:

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

Github 是这样给要点加注星标的:PUT/gists/:gist_id/star

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

长答案:

您的目标是使您的应用程序易于直观地使用。您的用户应该以最简单的方式使用您的应用程序。您的用户不应受到您所使用技术的限制或硬性指导。

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

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

记住:

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

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

谨防“ Shiny 物体综合症”。去谷歌上查询。

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

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

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

引用文献: https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful