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

Question

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

通常，我只使用自动递增键，因此添加的每个新记录都会增加ID号。

我曾想过，如果我使用这种方法，它将有效地产生如下所示的URI：

/people/11/addresses/52

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

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

无论如何，我想这里的问题是关于最佳实践的。 看到一个拥有另一个ID值这样的实体是否常见？ 这有哪些一般惯例？

Answer 1

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

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

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

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

在这种情况下，您可以省略详细地址的url。

Answer 2

您的方法是正确的。 另外，这些是通用规则（ 参考 ）：

- 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

网络上也有很多参考。 此页面是一个好的开始。 这些也很有用： slide1 ， devzone教程

Answer 3

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

要检索所有地址，正确的呼叫是/people/11/addresses 。 然后，您知道必须调用联接查询。