RESTFul API 设计建议

Question

我正在研究 RESTFul API 设计，但我对以下用例感到困惑：

我有用户和用户贷款的贷款。需要 API a) 用户管理 b) 获取所选用户的贷款信息。

用例 a) 相当简单。端点将通过 GET /api/users/ 来获取用户信息。 如何设计 API 端点来获取用户的负载信息：

GET /api/loans/<user unique id>/
or
GET /api/users/<user unique id>/loans

请注意，这与两者都用于唯一标识用户不同。

如有任何建议，我们将不胜感激。

谢谢你，
拉吉

Answer 1

REST 并不关心你的资源标识符使用什么拼写。

因此，标识符拼写很像变量名拼写；选择符合当地惯例的拼写是个好主意。

URI 规范将“分层信息”与非分层信息区分开来。人们可以合理地认为“鲍勃收集贷款”在层次上从属于“鲍勃”，并且标识符的拼写应该反映这一点

/api/users/12345
/api/users/12345/loans

这种拼写的另一个优点是，由于

相对引用

，引用从属于 Bob 的其他资源是微不足道的 uri(/api/users/12345/addresses) === uri(/api/users/12345/loans).resolve(../addresses)

但是，这对资源之间的关系没有任何影响。例如，对 

/api/users/12345

的成功不安全请求将使之前缓存的该资源表示无效，但这对

/api/users/12345/loans

根本没有任何影响。 例如：

GET /api/users/12345/loans
DELETE /api/users/12345

对于客户端而言，标识符拼写的相似性并不意味着这两个资源之间有任何特殊关系；即使用户资源已被删除，缓存中

loans

 资源的表示仍将被视为有效。

对于设计 RESTful API，特别是在处理资源之间的关系时，保持端点的清晰度和逻辑结构至关重要。在您描述的场景中，用户可以获取贷款，并且您需要获取特定于用户的贷款信息，RESTful 设计鼓励以分层方式表示资源及其关系。

Answer 2

GET /api/users/

/贷款

这种方法更加直观和 RESTful，原因如下： 它清楚地代表了用户与其贷款之间的关系，表明您正在访问属于特定用户的贷款。 它是可扩展的，允许未来扩展。例如，如果您稍后决定添加更多与用户贷款相关的操作，例如创建新贷款、获取特定贷款详细信息或更新贷款信息，则此结构自然会容纳这些添加内容（例如，POST /api/users/

/loans 为用户创建新贷款）。 这种方法与 RESTful 设计原则非常吻合，它鼓励从资源（在本例中为“用户”和“贷款”）和子资源（属于特定用户的贷款）角度进行思考。

获取/api/贷款//

虽然这种方法在技术上可行，但由于以下几个原因，它在 RESTful 设计原则方面不太直观： 这表明您直接通过用户的唯一 ID 获取贷款资源，这可能会造成混乱，因为贷款的主要标识符与用户的 ID 不直接相关。 它并没有清楚地代表用户及其贷款之间的层次关系。这可能意味着您正在全局访问贷款并按用户进行过滤，而不是访问用户的特定贷款子集。 结论： 针对您的用例的推荐方法是使用 GET /api/users/

/loans。这种设计更符合 RESTful 原则，清晰地表示用户和贷款之间的关系，对于使用您的 API 的开发人员来说更直观。它有效地传达了客户正在请求与特定用户相关的贷款，从而在 API 设计中保持清晰且逻辑的结构。