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

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

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

定义RESTful API的"Restful Objects"声明操作有效.

可以发现,启用/禁用可用操作,并且可以提供"禁用原因"反馈.

使用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