rest - REST API 中的信息性与唯一生成的 ID

Question

设计一个 RESTful API。我有两种识别资源(个人数据)的方法。通过数据库生成的唯一 ID 或为每个人输入的社会安全号码 (SSN)。 SSN 据说是唯一的，但可以更改。

使用 ID 对我来说是最方便的，因为它保证是唯一的，并且不会改变。因此资源的 URL 也始终保持不变:

GET /persons/12

{
  "name": Morgan
  "ssn": "840212-3312"
}

使用 SSN 的论据是它提供更多信息，API 客户端更容易理解。 SSN在周边系统中也使用较多:

GET /persons/840212-3321

{
  "name": Morgan
  "id": "12"
}

所以问题是:我是否应该采用第一种方法，并避免 SSN 可能发生变化的一些实现问题。也许提供一些从 SSN 转换为 ID 的辅助方法？

或者采用第二种方法。提供信息更丰富的 API。尽管必须处理一些不那么 RESTful 的奇怪之处，其中 URL:s 可能会因 SSN 更改而更改？

Answer 1

URL 设计是个人选择。但是为了给你一些与 Ray 已经提供的不同的例子，我会给你一些我自己的例子。

我有一个用户帐户资源并允许通过两个 URI 进行访问:

/users/12

和

/users/morgan

其中数值是自动递增的 ID，字母值是用户指定的系统上唯一的用户名。这些资源是不可缓存的，所以我不关心规范化，但是 /users 页面链接到字母表。

我的系统上没有其他资源具有两个唯一字段，因此通过 ID /jobs/123 和 /quotations/456 引用。

如您所见，我更喜欢复数 URI 段 ;-)
我认为“job 123”来自“jobs”集合，因此拥有一个“jobs”资源以及每个作业的子资源似乎是合乎逻辑的。

您不需要单独的 /search/ 区域来执行搜索，我认为将您的搜索条件直接应用于集合资源会更清晰:

/people?ssn=123456-7890  (people with SSN matching/containing "123456-7890")
/people?name=morgan      (people who's name is/contains "Morgan")

我有类似的东西，但只使用第一个字母作为过滤器:

/sites?alpha=f

列出所有以 F 开头的站点。您可以将其视为过滤器或搜索条件，这些术语只是同一枚硬币的不同方面。