资源之间的 REST 1:1 关系答案

【问题标题】：REST 1:1 relation between resources资源之间的 REST 1:1 关系
【发布时间】：2014-01-03 17:14:22
【问题描述】：

我想设计一个讨论公交车站的 REST API。

例如

    GET /stations/1asca2dac34
    {
        name:  'Queen str.'
        lat: 50.45
        lon: 9.63
    }

我现在的目标是表示车站之间的距离。例如，AAA 站和 BBB 站之间的距离是 5 公里。我不是 REST 设计方面的专家。设计这种 1:1 关系的最佳方式是什么？

我可以考虑以下解决方案，但我不确定它们是否适合 REST 风格。

GET /distances/?station1=AAA&station2=BBB
{
    uid: 123
    station1=AAA
    station2=BBB
    km: 5
}

GET /distances/AAA/BBB
{
    uid: 123
    station1=AAA
    station2=BBB
    km: 5
}

GET /distances/123
{
    uid: 123
    station1=AAA
    station2=BBB
    km: 5
}

【问题讨论】：

标签： api rest restful-url api-design

【解决方案1】：

另一种无需查询的 RESTful 可能性是使用 URI 分隔符。

GET /stations/{st_a;st_b}

通过这种设计，您的 URI 变得简单而干净。分号表示可互换的 ID（Richardson 第一本书）。

返回的 JSON 是一个简单的值。距离是我的资源，因为它是计算的值。

【讨论】：

【解决方案2】：

我建议您将站内的起点设为/stations/{id}，然后您可以从那里公开指向/stations/{id}/distances 的链接。第二个 URI 将列出从该站点到所有其他站点的距离，您希望如何呈现该数据取决于您。最终的 URI 将采用 /stations/{id-a}/distances/{id-b} 的形式，它可以返回一个非常简单的数字。作为一般规则，如果可以的话，我会避免使用查询字符串。

【讨论】：

【解决方案3】：

我会使用类似的东西：

/stations/1asca2dac34/distance?from=432dscas

客户的起点可能是 /stations，他将在其中获取所有车站（名称、ID、地理位置、公共汽车、火车等交通工具）的列表你的 API。

从那里开始，通过使用 HATEOAS，您可以提供所有底层资源的客户端链接，例如：

/stations/{id}/distance?from={id}

也许还有其他一些与电台相关的东西：

/stations/{id}/trains/timetable
/stations/{id}/trains/{train_id}/timetable
/stations/{id}/foobar

如果你从 /distances 开始有点奇怪，因为我无法“猜测”它会返回什么样的列表。让我提前说，您的选择都没有错，但底线是让您的客户消费者明智/“可猜测”。

同意 Joshua Moore 所说的问题。 “距离”资源是否对您的消费者有意义，或者是否可以从一个起点（例如车站）展开所有内容，因为这就是您的 API 的全部/唯一意义？

【讨论】：

很好地使用超媒体 - 很高兴看到。来自 /stations/AAA 的初始响应可以返回 /stations/AAA/distance?from={id} 形式的 URL 模板，这将使客户端能够在运行时发现 URL。然后应该用链接关系标记该 URL 模板，以便客户端可以通过 link-rel-id 查找模板。例如，请参阅 HAL，了解包含链接的媒体类型 (stateless.co/hal_specification.html)。

【解决方案4】：

您的所有示例实际上都是 REST 样式的 URI。这是一个观点和适用性的问题。考虑您的目标受众。 #1 很有意义，因为您正在为查询提供参数。 #2 对于 API 的使用者来说似乎很难理解，而 #3 则更加抽象，并假设 API 的使用者知道数据的 uid。

您应该问“其中哪一个最适合我的消费者需求？”

只是我的拙见。

【讨论】：