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

Question

我正在尝试定义REST API,但我遇到了一个问题.我有一个API用户可以执行的操作是相同的,但可以通过两种不同的方式完成.

例如,假设我的用户使用我的API来改变灯光的强度.我会有一个类似的URL

API /光/强度

用户必须更改强度的一个选项是设置为最大亮度的%,另一个选项是将强度设置为精确值,以流明(有一个检测器)并且他可以传递"精度"可以是低,中,高(它会改变达到正确强度所需的时间).

我希望用户能够获得当前的强度,这意味着他在哪种模式下,取决于模式,%或流明的值和精度.

这是我丢失的地方,我的GET将返回一个JSON对象,例如,发送类似的东西是否可以

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

当我处于"百分比"模式时

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

当我处于"流明"模式时？

如果这似乎没问题,我怎么告诉用户他应该解析哪种类型的"对象"？

让用户发送更改的最佳方法是什么？我在考虑有两个URL,每个模式一个,如PUT/api/light/intensity/exact和PUT/api/light/intensity/percent

两者都在等待类似于上面的JSON对象,没有Mode.

Answer 1

使用HTTP内容协商.这允许:

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

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

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头部知道如何解释JSON主体.在此示例中,它以"百分比"模式处理请求.

如果使用了第二种内容类型,客户端和服务器将知道在"Lumes"模式下解释请求/响应.

编辑:请注意,GET和 PUT请求使用相同的 URL,因为请求是关于相同的资源:光强度.所有不同的是该资源的表示.处理此问题的正确方法是内容类型.