REST:如果API返回两种类型的响应，它会被认为是restful吗？

Question

我们有股票网站，我们帮助买家与卖家联系。我们正在创建API，让买家推送他们的联系方式，并返回卖家的详细信息。这是事务，并记录在我们的数据库中。我们创建了如下接口：

请求是POST，URL如下所示：

/api/leads

请求正文如下所示：

{
  "buyermobile": "9999999999",
  "stockid": "123"
}

响应看起来像这样：

{
  "sellermobile" : "8888888888",
  "selleraddress": "123 avenue park"
}

我们有了一个新的要求，即我们需要发回PDF URL (而不是"sellermobile“和"selleraddress")。此PDF URL将包含卖家详细信息，以防它来自我们的客户之一。

我们已经修改了相同的接口，现在请求正文如下：

{
  "buyermobile": "9999999999",
  "stockid": "123",
  "ispdf": true
}

响应看起来像这样：

{
  "sellerdetailspdf" : "https://example.com/sellerdetails-1.pdf",
}

这样做是不是很轻松呢？或者我们应该创建单独的API来获取PDF格式的响应？

Answer 1

我不会这样做的。当您需要添加XLS时会发生什么？您是否也将"isxls“添加到请求中？

我会考虑的事情：

使用mime类型进行内容协商。发布相同的请求，并在Accept头中指定您期望返回的内容- JSON、PDF等。然后实际得到的是报告，而不是指向报告的链接，这可能会更好，也可能不会更好。

或者-

在典型的潜在客户响应中包含一个链接。

{
    "sellermobile" : "8888888888",
    "selleraddress": "123 avenue park",
    "_links": {
        "seller-details-pdf": "https://example.com/sellerdetails-1.pdf"
    }
} 

或者-

支持在响应中指定类型的查询参数。

或者-

只有一个属性来指定响应中的类型，而不是布尔值。当您添加新的响应类型时，扩展起来更加简洁。

前两个选项的好处是，您不需要客户端对单个请求处理多个响应类型。这并不是任何规范都禁止的，但这对客户来说很烦人。试着不要惹恼你想付钱给你的人。:)

Answer 2

同样，这个实现在我看来也很好，但是您可能会考虑将PDF URL返回到另一个端点，这样您的请求正文对于api/lead和/lead下的所有后续端点都是相同的，比如api/lead/pdf。允许您的路由和其他代码处理小部分任务，而不是具有处理多个标志和多个代码路由的路由。

Answer 3

这对我来说很好-相同类型的输入应该给出相同类型的响应，但在你的例子中，你有两种不同类型的输入-一种有"ispdf“标志，另一种没有。因此，使用两种不同类型的响应进行响应是一致的，一种使用PDF链接，另一种不使用PDF链接。

这仍然是你想要记录的东西，但基本上它是一个正确的实现。