RESTful API: collection URL return 应该是什么？

Question

假设我有一个包含客户及其订单的数据库。每个客户都有姓名、地址等一般信息。每个订单都有购买商品、支付金额等信息。数据库通过 RESTful API 公开。

据推测，RESTful API URL 上的 GET 类似于

/customers/101/orders/47/

预计 return 客户 101 的订单 47 的信息（购买的商品、支付的金额等）。

我还假设 GET 对以下 URL:

/customers/101/orders/

预计 return 客户 101 的所有订单信息。

但是，GET 应该对下面的什么 URL return?

/customers/101/

是否应该 return 客户 101 的所有订单？
它 return 应该只是客户 101 的姓名、地址等吗？
是否应该 return 客户 101 和他们的姓名、地址等的所有订单？

我的问题显然假设有一个 "right answer" 或推荐的最佳实践 RESTful API URL 应该 return。

Answer 1

我喜欢这个问题。我认为这是非常特定于应用程序的。我的想法是只返回一个匿名对象或 JSON 该客户特定功能的对象以及他们的个人信息（姓名和地址）。

这样我就可以检查他们的授权能力以及他们是谁，并使用该信息或验证他们可以做他们想做的事（也许是虚假的廉价安全层？）...

祝你好运！

Answer 2

它将 return 客户信息。此 URL 指向客户资源，因此它应该 return 客户相关数据。

例如，如果您查看 GMail REST API，类似的请求可以 return 订单 ID。

但不是订单信息。

Answer 3

假设每个客户的订单数量不是很大，我会按如下方式构建。

GET /customers/101
{
    "id": 101,
    "name": "John Smith",
    "orders": [
        "/orders/47",
        "/orders/52"
    ],
    ...
}

GET /orders/47
{
    "id": 47,
    "customer": "/customer/101",
    ...
}

要点：

不要在 URL 中嵌套资源
- 嵌套阻碍了你以后重组事物的能力。当您想添加多客户订单时会发生什么？
Link 个资源使用它们的 URI

Answer 4

URL 的结构并不是 RESTful 的结构；相反，您应该提供一个对象，其中包含以易于发现的方式指向其他数据的链接。

因此，如果调用者到目前为止已对

执行 GET

/customers

...您可能希望 return 包含 "Customer" 个对象的列表。然后，每个 Customer 对象将包含指向适当对象的链接及其 URI。在您的情况下，每个 Customer 对象可能符合以下行：

{
    "customer": {
        "id": 101,
        "self": {
            "url": "http://service.yourdomain.com/customers/101",
            "recommended_mediatype": "application/x.yourdomain.customer.v1"
        }
        "orders_list": {
            "url": "http://service.yourdomain.com/customers/101/orders",
            "recommended_mediatype": "application/x.yourdomain.order.v1"
        }
    }
}

这为您解决了两个问题：

是否 return 订单，仅地址，或两者： 客户端可以通过在 GET 中提供不同的 MediaType 来决定这一点.上面的 Customer 对象推荐 x.yourdomain.order.v1 的 MediaType，但您可能支持不同的表示类型（比如）x.yourdomain.order-address .v1 仅包含订单的地址数据。在这方面，您在同一个 URI 端点提供许多不同的资源表示。
不预先确定您的 URI： 通过将 URI 嵌入到父对象（客户）中，您不会向客户公开 URI 结构；使将来改变更可行。

希望对您有所帮助！

RESTful API: collection URL return 应该是什么？

RESTful API: What should a collection URL return?

rest

restful-url