自然键和RESTful URL

Question

我正在设计一个RESTful API，其中所有资源都使用数字主键。然而，一种类型的资源具有方便的自然键，我希望能够使用它作为指定单个资源的可选方式。为了保持一致性，所有资源都将通过其主键访问。

目前为止，我可以这样做（假设23是主键）：

mysite.com/api/v0/sites/23/

但我想知道是否有一种成语化的方法来指定资源的另一个自然键。

到目前为止，我考虑做类似这样的事情：

mysite.com/api/v0/sites/?domain-name=someothersite.com/

因此，一个个人网站的资源将可以通过其主键和自然键（域名）来访问。我的主要关注点是以惯用方式完成这一点，因为我希望使API尽可能简单易用。

- rectangletangle

---

很好，我的意思是我从未想过在例子中使用v0，但这很有道理。 :-) - inf3rno

Answer 1

在您的情况下，主键（整数）总是可以轻松地与域名（包括句点的字符串）区分开来。允许同时在URL的同一位置使用这两个参数似乎是完全有效的（并且直观的）：

mysite.com/api/v0/sites/23
mysite.com/api/v0/sites/someothersite.com

文档化也很简单，因为每个内容都是一个站点的唯一标识符：

mysite.com/api/v0/sites/{id}
  id: primary key or fully-qualified domain name

- Mike Dunker

Answer 2

我也曾苦恼于找到一个令人满意的答案。我已经开始按照Mike Dunker的建议实施，但最终遇到了一些资源，无法区分代理键和自然键。那时，我意识到我宁愿采用统一的方法，而不是混合不同的方式 - 就像你所说的，使用一些惯用语。

我发现另一种方法在http://soabits.blogspot.de/2013/10/url-structures-and-hyper-media-for-web.html中描述（在“自然键，代理键，URL别名和资源复制”下）。

这个想法是将两种可能的键方案之一定义为规范方案，并通过向URI添加一个段并使用HTTP 303（See Other）重定向到规范URI来实现另一个方案。

在您的示例中，可以将mysite.com/api/v0/sites/23/作为规范ID，以mysite.com/api/v0/sites/domain-name/someothersite.com/为例，回复HTTP 303并包含一个位置标头，其中包含mysite.com/api/v0/sites/23/(或反之亦然)。使用重定向URI别名代替“复制”相同资源对于http://www.w3.org/TR/webarch/#uri-aliases中提到的原因非常有用。

我之所以不采用这种解决方案的原因是我们项目设置中可能会增加额外的HTTP往返成本。

- Hein Blöd

Answer 3

这里有一个比Mike's更强大的想法，它使用key参数来表示资源ID所指的自然键：

mysite.com/api/v0/sites/23

并且

mysite.com/api/v0/sites/someothersite.com?key=domain-name

在您的控制器中，您可以验证关键参数仅为自然键，而不是查询唯一索引的表元信息。如果您不喜欢污染查询字符串，您也可以使用HTTP标头。

- malhal

Answer 4

请注意，ORM实体或领域实体不是资源。这些实体和资源之间可以进行映射。资源是应用程序接口概念，您可以使用资源和对这些资源的操作来描述服务的接口。

因此，您的主键不标识资源，而标识实体。资源由URI标识。URI不是唯一标识符，因此您可以使用多个URI来标识单个资源。

马克是正确的，您可以使用类似的URI模板。

mysite.com/api/v0/sites/{id}
mysite.com/api/v0/sites/{hostname}

如果您的路由框架支持按类型区分路由。因此，如果类型为数字，则将运行id路由，如果类型与主机名正则表达式模式匹配，则将运行主机名路由。否则，您可以合并这两个路由，并使用代码手动处理它们之间的差异。

- inf3rno