用于自定义响应数据的RESTful API端点

Question

我正在构建一个RESTful API，其中有一个名为solar_systems的资源。 solar_sytems具有id（int），system_size（int），system_cost（int）列以及许多其他列。

我了解API端点将是 -

/ v1 / solar-systems - 适用于所有系统

/ v1 / solar-systems / {id} - 适用于单个系统

我必须通过查询参数进行过滤，搜索，排序等。

但是，如果我需要某种自定义数据，例如每个system_size需要平均system_cost，那么API端点的最佳做法是什么。

如果我使用 - / v1 / solar-systems / average-system-cost会不会很愚蠢？

请从您的经验中获取您的意见。

Answer 1

使用/ v1 / solar-systems / average-system-cost

根本不是愚蠢的

很容易陷入这样一个事实：技术上平均系统成本不是资源。但它是一块有用的检索数据。最终，REST的目标是使API易于理解和可读。获取有用数据的特定端点肯定属于那个。

Answer 2

  

如果我使用/v1/solar-systems/average-system-cost会不会很愚蠢？

REST架构不强制执行任何URI设计 ^{（请参阅下面的注释）}。完全取决于您选择更好地识别资源的URI。

但是我可能会使用query parameters来选择要在响应中返回的字段。类似于/v1/solar-systems?fields=average-system-cost。

^{注1： Roy T. Fielding的论文chapter 5中描述的REST架构风格定义了一系列约束，后面的应用程序必须遵循这些约束这样的架构。 然而，它没有说明URL必须是什么样的。}

^{注意2：另一方面，由Martin Fowler撰写的popular article的示例解释由Leonard Richardson定义的模型建议一个看起来友好且易于阅读的网址结构。}