RESTful API：集合URL应该返回什么？

比方说，我有一个客户和他们的订单数据库。 每个客户都有一般信息，如姓名，地址等。每个订单都包含购买物品，支付金额等信息。数据库通过RESTful API公开。

据推测，在RESTful API URL上使用GET

/customers/101/orders/47/

预期将返回客户101的订单47的信息（购买物品，支付金额等）。

我还假定在以下URL上有一个GET：

/customers/101/orders/

预计将返回客户101的所有订单的信息。

但是，以下网址上的GET应该返回什么？

/customers/101/

它是否应该返回客户101的所有订单？

它应该只返回客户101的名称，地址等吗？

它是否应该返回客户101的所有订单及其名称，地址等？

我的问题显然假设对于RESTful API网址应返回的内容有“正确答案”或推荐的最佳做法。

---

它会返回客户信息。 此网址指向客户资源，因此应返回客户相关数据。

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

但不是订单的信息。

---

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

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

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

关键点：

不要在URL中嵌套资源

嵌套会妨碍你以后重构事物的能力。 当你想添加多客户订单时会发生什么？

使用它们的URI链接资源

---

URL的结构并不是使其成为RESTful的原因; 相反，您应该以容易发现的方式提供包含指向其他数据链接的对象。

所以，如果调用者到目前为止已经做了GET

/customers 

...您可能期望返回“客户”对象列表。 然后每个Customer对象将包含指向适当对象的链接及其URI。 在你的情况下，每个客户对象可能包含以下内容：

{
    "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"
        }
    }
}

这为您解决了两个问题：

是否返回订单，只是地址，还是两者：客户可以通过在GET中提供不同的MediaType来决定这一点。 上面的Customer对象推荐使用x.yourdomain.order.v1的MediaType，但是您可能支持不同的表示类型（比如说） x.yourdomain.order-address.v1 ，它只包含订单的地址数据。 在这方面，您在同一个URI端点上提供了许多不同的资源表示。

不预先确定您的URI：通过将URI嵌入到父对象（Customer）中，您不会将URI结构公开给客户端; 使未来改变更加可行。

希望有所帮助！

链接地址: http://www.djcxy.com/p/7007.html

上一篇: RESTful API: What should a collection URL return?

下一篇: RESTful: How to perform different actions on the same url?