自定义动作RESTful接口URL路径

Question

我有一个预算实体。

在某种程度上，这个应用程序可以让你为客户创建一个新的预算。在保存预算之前，您可以选择生成预览，其中会显示基于您的选择的总金额。

这些计算是在服务器中完成的，因此我需要公开适当的端点，但我不确定该端点应该是什么。

我正在考虑发送所需参数的[GET] http://example.com/budgets/preview/。

这是正确的吗？这将指向budget类中的preview()方法。

那我已经保存的预算的预览呢？

[GET] http://example.com/budgets/{ID}/preview/

Answer 1

请记住，REST就是在需要的时候拥有一个资源的多个表示，所以首先要确定的是资源是什么，以及它们之间是否存在任何关系。

在我看来，您似乎有预算作为资源和budgetPreview作为资源的概念，并且您也希望能够在以后检索它们中的任何一个。

我建议使用下面的URI‘似乎

GET

这将在服务器上生成并返回一个budgetPreview，而不存储它。IMO在API中似乎不清楚创建budgetPreview的路线是嵌套在预算下的。我还主张稍微远离“所有端点必须是名词”，转而支持可以在资源上执行或使用资源执行的业务操作。如果有人提出异议，您可以将generate更改为"generateRequest"，因为实际上您正在向服务器传递一个填充了表示生成budgetPreview请求的值的文档。我在这里做的一个假设是，服务器构建budgetPreview所需的所有信息都是在GET请求中从客户端传递过来的。

这里需要注意的一件事是，您需要将URI中的所有信息作为查询参数包含在内，因为返回的值将根据参数的不同而有所不同。在GET的主体中传递值，然后赋予该主体语义含义(即，基于主体中的值创建不同的资源)将破坏缓存(如果您正在执行任何操作)。

GET

返回所有已存储的budgetPreviews

PUT{GUID}

在这里使用put创建资源，并允许客户端确定id，这意味着在超时的情况下可以重试存储资源的请求，并允许幂等性。在存储预算预览的同时，您可以在参数中提供预算的Id并将它们链接起来。

GUID{GET}/budgetPreview

GET{GUID}

这些是标识相同资源的不同URI，并允许客户端以不同的方式使用budgetPreview

一个额外的要点是不要混淆底层资源或实现细节，例如调用哪个方法与面向公共的API看起来是什么样子。目标是让你的面向公众的API尽可能地适合客户，你的表现是专注于对客户合同进行建模，而不是将底层资源持久化。

此外，一位智者曾经告诉我的另一件事是，记住您有无限的URI可供您随意使用，所以当它为您的API提供清晰度，并且您的客户正是他们想要的时候，不要害怕创建更多的URI。

Answer 2

不要重载/budgets之后的URL段以包含ID或“预览”。相反，您可以使用

[GET]  /budgets/{id}
[POST] /budget-previews
       > returns a preview given the data in the body
[GET] /budget-previews/{id}
       > returns a preview given data on the server

现有预算可以提供其预览的链接，而新预算可以请求预览。如果愿意，您可以在执行POST /budget-previews时单独保存预览，然后可能使用POST /budgets?previewId={}从预览创建预算(或将预览id放在POST的正文中)。我会避免使用预算id作为预览id，以防您稍后决定要单独保存预览。

如果有也不会有其他类型的预览，请考虑使用/previews而不是budget-previews。