RESTful API 设计：“拥有”资源的 ID 值答案

【问题标题】：RESTful API Design: ID values for "owned" resourcesRESTful API 设计：“拥有”资源的 ID 值
【发布时间】：2015-12-26 05:31:59
【问题描述】：

在设计 RESTful API 时，资源所有权是设计 URI 时的一个考虑因素。就我而言，我正在开发一个 API，其中我的两个实体将是人员和地址。每个人可以有多个地址，因此在数据库中它们将位于不同的表中。

通常我只使用自动递增键，所以每增加一条新记录都会增加 ID 号。

我的一个想法是，如果我使用这种方法，它会有效地生成这样的 URI：

/people/11/addresses/52

在这种情况下，person 11 没有 52 addresses。只是人 11，其地址的 ID 为 52。

另一方面是我是否会使用这样的 URI。地址通常不会由客户端自行检索，而是作为通过单个 API 调用检索的人员对象的一部分（/people/11 将检索与该人员关联的所有地址）。

无论如何，我想这里的问题是关于最佳实践的。是否经常看到另一个拥有类似 ID 值的实体？这方面的一般做法是什么？

【问题讨论】：

标签： api rest

【解决方案1】：

你的方法是正确的。这些也是一般规则（reference）：

- An API is a user interface for a developer - so put some effort into making it pleasant
- Use RESTful URLs and actions
- Use SSL everywhere, no exceptions
- An API is only as good as its documentation - so have great documentation
- Version via the URL, not via headers
- Use query parameters for advanced filtering, sorting & searching
- Provide a way to limit which fields are returned from the API
- Return something useful from POST, PATCH & PUT requests
- HATEOAS isn't practical just yet
- Use JSON where possible, XML only if you have to
- You should use camelCase with JSON, but snake_case is 20% easier to read
- Pretty print by default & ensure gzip is supported
- Don't use response envelopes by default
- Consider using JSON for POST, PUT and PATCH request bodies
- Paginate using Link headers
- Provide a way to autoload related resource representations
- Provide a way to override the HTTP method
- Provide useful response headers for rate limiting
- Use token based authentication, transported over OAuth2 where delegation is needed
- Include response headers that facilitate caching
- Define a consumable error payload
- Effectively use HTTP Status codes

网上也有很多参考资料。 This 页面是一个好的开始。这些也很有用：slide1, devzone tutorial

【讨论】：

谢谢，这太棒了。阅读它让我想到了另外两个问题。 1）链接标题中的分页是什么意思？我正在考虑为此使用请求参数，那么我该怎么做呢？ 2) REST 安全/身份验证是我现在正在研究的东西。我通常只使用 Spring Security，你有什么技巧可以使用 RESTful 吗？具体如何保持无国籍状态？
EFC 5988 引入的链接标头，旨在指示 Web 上资源之间的关系：Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next", <https://api.github.com/user/repos?page=50&per_page=100>; rel="last" 和基于令牌的身份验证是您 API 中的一个令牌：https://api.test.com/get/some/info?token=12345 这就是为什么您总是需要 ssl ！隐藏令牌！

【解决方案2】：

当您以个性化的方式为人员实体返回地址详细信息时，您通常会使用如下资源：/people/11/addresses/52。

例如，如果您有实体：可以有地址的人员和办公室，对于人员您希望仅显示国家/地区，对于办公室您希望显示地址的所有详细信息。

另一方面，如果您不需要自定义，您也可以使用类似的 url： /address/12 ，因为这样缓存响应会更容易。

客户通常不会自行检索地址，但作为单个 API 调用检索的人员对象的一部分（/people/11 将检索与该人关联的所有地址）。

如果是这种情况，您可以省略详细的地址 url。

【讨论】：

【解决方案3】：

是的，这是在 API 中应用多对多关系的正确方法。只记得在返回值时检查 id2 是否属于 id1。

要检索所有地址，正确的调用是/people/11/addresses。然后你知道你必须调用一个连接查询。

【讨论】：