REST URI 设计：具有复数名称的资源

Question

我有一个客户集合，每个客户都有一个 relationships 资源，如下所示：

{
  "customerId" : "string",
  "accounts" : [{
    "accountId" : "string",
     ...
  }],
  "profiles" : [{
    "profileId" : "string",
     ...
  }]
}

我正在构建一个 REST api 以提供对该资源和子资源（如 accounts 和 profiles 的访问。

这是我想出的 URI：

/customers/{id}/relationships - return 上述资源
/customers/{id}/relationships/accounts - 至 return accounts 子资源
/customers/{id}/relationships/profiles - 至 return profiles 子资源

但我看到的一个问题是 relationships 资源看起来像一个集合。因此，预计在那之后会有一个 {relationshipId} 。但实际上它是一个单一的资源。我如何为此设计 URI？

Answer 1

如果 'relationships' 是单个对象而不是集合，您可以采用多种方式。

完全删除它，这样您就有了 /customers/{id}/accounts 和 /customers/{id}/profiles
将其重命名为其他名称/customers/{id}/related/accounts
保持原样...这仍然有效，因为 'accounts' 和 'profiles' 成为关系集合下的 id (/customers/{id}/relationships/{id(accounts|profiles) }

遵守标准总是好的。但通常你会花太多时间担心一些小问题，最终无论你走哪条路，都不会产生很大的不同。

Answer 2

您需要确定关系是文档还是集合。见此定义：

https://restfulapi.net/resource-naming/

如果您认为它是一个集合，那么 /customers/{id}/relationships/accounts 是正确的，其中 accounts 是集合中资源的 ID。

如果您将其视为文档，那么您请求的是文档的有限视图，如果您希望按照 OData 方式进行操作，可以使用类似 /customers/{id}/relationships?$select=accounts 的内容

https://docs.microsoft.com/en-us/aspnet/web-api/overview/odata-support-in-aspnet-web-api/using-select-expand-and-value#using-select

REST URI 设计：具有复数名称的资源

REST URI design: Resource with plural name

rest

uri

api-design