REST API 设计 - 单个通用端点或多个特定端点
REST API Design - Single General Endpoint or Many Specific endpoints
这是一个比较主观的问题，但我还是想听听别人的意见
我正在设计一个 REST Api，它将被内部系统（最多几个客户端应用程序）访问。
一般API需要更新不同汽车品牌的参数。每个汽车品牌都有大约 20 个属性，其中一些是所有汽车品牌共享的，一些是每个品牌特定的。
我想知道什么是更好的设计此 API 端点的方法。
我是否应该使用单个端点，它接收一个字符串 - 即汽车品牌所有属性的 JSON，以及汽车品牌的 ID。
或者我应该为每个汽车品牌提供一个单独的端点，它的主体具有该汽车品牌所需的确切属性。
所以在第一种方法中，我有一个端点，它有一个 string 参数，我希望它是一个 JSON 和所有必要的值
PUT /api/v1/carBrands/
而在第二种情况下的第二种方法中，我对每种汽车品牌都有一个端点，并且每个端点都有一个 类型的 dto 对象 代表它需要的所有值。
PUT /api/v1/carBrand/1
PUT /api/v1/carBrand/2
.
.
.
PUT /api/v1/carBrand/n
第一种方法似乎节省很多重复代码——毕竟唯一区别在于参数集。 但是，因为它接受任意字符串，最终用户无法知道他应该传递什么——他需要有人告诉他and/or read from documentation .
第二种方法可读性更高，任何人都可以填写数据，因为他们知道它是什么。但它主要涉及将相同的代码复制大约 20 次。
我真的很难选择一个选项，因为这两种方法都有其缺点。我该如何判断哪个更好
I am wondering what is a better approach to the design for the endpoints of this API.
根据您的示例，您似乎在询问 resource 设计，特别是您是应该使用一个大型资源还是一系列较小的资源。
REST 没有回答这个问题……无论如何，没有直接回答。 REST 所做的是识别缓存粒度处于 resource 级别。如果有两条信息，并且你想让一条信息失效也使另一条信息失效，那么这两条信息应该是同一个资源的一部分，也就是说它们应该使用相同的URI访问。
如果这不是您想要的，那么您可能应该倾向于使用分离的资源。
我不一定期望对 Ford 进行编辑会强制使我的本地副本 Ferrari 失效，因此这表明我可能希望将它们视为两个不同的 资源，而不是两个子资源.
比较
/api/v1/carBrands#Ford
/api/v1/carBrands#Ferrari
和
/api/v1/carBrands/Ford
/api/v1/carBrands/Ferrari
在前一种情况下，我的缓存中有一个资源 (/api/v1/carBrands)；我对其所做的任何更改都会使整个资源无效。在后一种情况下，我缓存了两个资源；更改一个会忽略另一个。
使用其中之一并没有错误；两者都很好，并且有很多历史。他们做出了不同的权衡，一个或另一个可能更适合您今天要解决的问题。
这是一个比较主观的问题，但我还是想听听别人的意见
我正在设计一个 REST Api，它将被内部系统（最多几个客户端应用程序）访问。
一般API需要更新不同汽车品牌的参数。每个汽车品牌都有大约 20 个属性，其中一些是所有汽车品牌共享的，一些是每个品牌特定的。
我想知道什么是更好的设计此 API 端点的方法。
我是否应该使用单个端点，它接收一个字符串 - 即汽车品牌所有属性的 JSON，以及汽车品牌的 ID。
或者我应该为每个汽车品牌提供一个单独的端点，它的主体具有该汽车品牌所需的确切属性。
所以在第一种方法中，我有一个端点，它有一个 string 参数，我希望它是一个 JSON 和所有必要的值
PUT /api/v1/carBrands/
而在第二种情况下的第二种方法中，我对每种汽车品牌都有一个端点，并且每个端点都有一个 类型的 dto 对象 代表它需要的所有值。
PUT /api/v1/carBrand/1
PUT /api/v1/carBrand/2
.
.
.
PUT /api/v1/carBrand/n
第一种方法似乎节省很多重复代码——毕竟唯一区别在于参数集。 但是，因为它接受任意字符串，最终用户无法知道他应该传递什么——他需要有人告诉他and/or read from documentation .
第二种方法可读性更高，任何人都可以填写数据，因为他们知道它是什么。但它主要涉及将相同的代码复制大约 20 次。
我真的很难选择一个选项，因为这两种方法都有其缺点。我该如何判断哪个更好
I am wondering what is a better approach to the design for the endpoints of this API.
根据您的示例，您似乎在询问 resource 设计，特别是您是应该使用一个大型资源还是一系列较小的资源。
REST 没有回答这个问题……无论如何，没有直接回答。 REST 所做的是识别缓存粒度处于 resource 级别。如果有两条信息，并且你想让一条信息失效也使另一条信息失效，那么这两条信息应该是同一个资源的一部分，也就是说它们应该使用相同的URI访问。
如果这不是您想要的，那么您可能应该倾向于使用分离的资源。
我不一定期望对 Ford 进行编辑会强制使我的本地副本 Ferrari 失效，因此这表明我可能希望将它们视为两个不同的 资源，而不是两个子资源.
比较
/api/v1/carBrands#Ford
/api/v1/carBrands#Ferrari
和
/api/v1/carBrands/Ford
/api/v1/carBrands/Ferrari
在前一种情况下，我的缓存中有一个资源 (/api/v1/carBrands)；我对其所做的任何更改都会使整个资源无效。在后一种情况下，我缓存了两个资源；更改一个会忽略另一个。
使用其中之一并没有错误；两者都很好，并且有很多历史。他们做出了不同的权衡，一个或另一个可能更适合您今天要解决的问题。