REST API: 距离测量单位

Question

距离的有利测量单位取决于文化。

例如，英尺可能优于米。这将使 API 的某些消费者无法接受以下响应模型：

GET [uri]
{
    ...
    "distanceInMetres": 256
}

也许客户应该能够提供他们的文化偏好：

GET [uri]?culture=en-US
{
    ...
    "distance": {
        "value": 840,
        "unit": "ft"
    }
}

这是一种可以接受的处理方式吗？我似乎找不到任何 最佳实践 或标准。

Answer 1

从 JSON 的角度来看，备选方案 2 肯定是可行的方法。它很容易扩展，不需要更改请求语义来支持其他 regions/units.

使用 HTTP 参数 "to adjust" 对象表示也完全可以。

虽然不是真正符合经典 REST 原则，但在某些情况下使用路径元素提供此类参数非常实用。

GET [/app/en-US/<resource-id>]?params1=

如果您的 API 需要一些参数来处理大部分请求（例如，传递特定区域的值），这就有意义了。

Answer 2

第二种方法似乎完全正确 - return 与单位的距离。但是，使用查询参数似乎不是这个主意。

对于各种 language-specific 功能，最好使用 header。甚至还有一个 header - Accept-Language 但它不适合这里。查询参数应该用于更改响应数据本身而不是它们的呈现方式，除非您使用预定义的查询参数来获取字段的子集，例如

REST API: Distance unit of measurement