json - REST资源根据状态返回不同的对象

Question

我正在尝试定义REST API，但我遇到了一个要求的问题。
我有一个 Action ，使API用户可以做到这一点，但是可以通过两种不同的方式来完成。

例如，假设我的用户使用我的API来更改灯光的强度。我将有一个类似的网址

api/光照/强度

用户必须更改强度的一个选项是将强度设置为最大光度的百分比，另一个选项是将强度设置为以流明为单位的精确值(有一个检测器)，并且他可以通过“精度”可以是低，中和高(它会更改达到正确强度所需的时间)。

我希望用户能够获取当前强度，这意味着他处于哪种模式，并取决于模式，流明百分比或以流明为单位的值以及精度。

这是我迷路的地方，例如，我的GET将返回JSON对象，是否可以发送类似

{
   "Mode" = "Percent",
   "Percent" = 50.5
}

当我处于“百分比”模式时，

{
   "Mode" = "Exact",
   "Lumens" = 200,
   "Precision" = "High"
}

当我处于“流明”模式时？

如果看起来还可以，我如何告诉用户他应该解析哪种类型的“对象”？

允许用户发送其更改的最佳方法是什么？我当时正在考虑有两个网址，每个模式一个，例如
PUT/api/light/intensity/exact和PUT/api/light/intensity/percent

而且两者都在等待与上述类似的JSON对象，但没有Mode。

Answer 1

使用HTTP Content negotiation。这允许:

客户端告诉服务器它想要资源的哪种表示形式GET，

服务器告诉客户端它返回给客户端的资源的哪种表示形式

客户端告诉服务器将PUT编码到服务器的资源的表示形式。

定义两种供应商内容类型:

application/vnd.com.example.light.intensity.percentage+json

application/vnd.com.example.light.intensity.lumens+json

客户端告诉服务器它想要两个:

GET /api/light/intensity/
Accept: application/vnd.com.example.light.intensity+percentage

服务器响应:

200 OK
Content-Type: application/vnd.com.example.light.intensity+percentage

{
   "Percent" = 50.5
}

客户想改变强度:

PUT /api/light/intensity/
Content-Type: application/vnd.com.example.light.intensity+percentage

{
   "Percent" = 42.7
}

服务器从 Content-Type header 中知道如何解释JSON主体。在此示例中，它以“百分比”模式处理请求。

如果使用第二种内容类型，则客户端和服务器将知道以“Lumes”模式解释请求/响应。

编辑:请注意， GET和 PUT请求使用相同的URL，因为这些请求具有相同的资源:光强度。唯一不同的是此资源的表示形式。处理此问题的正确方法是内容类型。