REST API 设计 - 单个通用端点或多个特定端点

Question

这是一个比较主观的问题，但我还是想听听别人的意见

我正在设计一个可由内部系统(最多几个客户端应用程序)访问的 REST Api。

一般来说，API 需要更新不同汽车品牌的参数。每个汽车品牌都有大约 20 个属性，其中一些属性在所有汽车品牌之间共享，有些是针对每个品牌的。

我想知道设计此 API 端点的更好方法是什么。

我是否应该使用单个端点，它接受一个字符串 - 这是汽车品牌所有属性的 JSON，以及汽车品牌的 ID。

或者我应该为每个汽车品牌提供一个单独的端点，该端点具有该汽车品牌所需的确切属性。

因此，在第一种方法中，我有一个具有 的端点。字符串 我希望是具有所有必要值的 JSON 的参数

PUT /api/v1/carBrands/

而在第二种情况下的第二种方法中，我对每种汽车品牌都有一个端点，每个端点都有一个 键入的 dto 对象 代表它需要的所有值。

PUT /api/v1/carBrand/1
PUT /api/v1/carBrand/2
.
.
.
PUT /api/v1/carBrand/n

第一种方法好象 保存 很多 重复 代码 - 毕竟唯一的区别是参数集。 然而 ，因为这接受任意字符串，最终用户无法知道他应该通过什么 - 他需要有人告诉他和/或从文档中阅读。

第二种方法更具可读性，任何人都可以填写数据，因为他们知道它是什么。但它主要涉及复制大约 20 次相同的代码。

我真的很难选择一个选项，因为这两种方法都有其缺点。我应该如何判断什么是更好的选择

Answer 1

I am wondering what is a better approach to the design for the endpoints of this API.

根据您的示例，您似乎在询问 resource设计，尤其是您应该使用一种大型资源还是一系列较小的资源。

REST 没有回答这个问题……无论如何也不是直接回答。 REST 所做的是确定缓存粒度在资源级别。如果有两条信息，并且您希望一条信息的无效也使另一条无效，那么这些信息应该是同一资源的一部分，也就是说，应该使用相同的 URI 访问它们。

如果这不是您想要的，那么您可能应该倾向于使用分离的资源。

我不一定期望对 Ford 进行编辑应该强制我的本地副本 Ferrari 失效，这表明我可能希望将它们视为两种不同的资源，而不是两种子资源。

相比

/api/v1/carBrands#Ford
/api/v1/carBrands#Ferrari

和

/api/v1/carBrands/Ford
/api/v1/carBrands/Ferrari

在前一种情况下，我的缓存中有一个资源 (/api/v1/carBrands)；我对它所做的任何更改都会使整个资源无效。在后一种情况下，我缓存了两个资源；改变一个忽略另一个。

使用其中之一并没有错；两者都很好，并且有很多历史。他们进行了不同的权衡，其中一个可能更适合您今天要解决的问题。