REST API sub resources, data to return?

Question

If we have customers and orders, I'm looking for the correct RESTful way to get this data:

{
  "customer": {
    "id": 123,
    "name": "Jim Bloggs"
    "orders": [
      {
        "id": 123,
        "item": "Union Jack Keyring",
        "qty": 1
      }, {
        "id": 987,
        "item": "London Eye Ticket",
        "qty": 5
      }
    ]
  }
}

1. GET /customers/123/orders
2. GET /customers/123?inc-orders=1

Am I correct that the last part/folder of the URL, excluding query string params, should be the resource returned..?

If so, number 1 should only return order data and not include the customer data. While number 2 is pointing directly at customer 123 and uses query string params to effect/filter the customer data returned, in this case including the order data.

Which of these two calls is the correct RESTful call for the above JSON..? ...or is there a secret number 3 option..?

Answer 1

You have 3 options which I think could be considered RESTful.

1) GET /customers/12 But always include the orders. Do you have a situation in which the client would not want to use the orders? Or can the orders array get really big? If so you might want another option.

2) GET /customers/123, which could include a link to their orders like so:

{
  "customer": {
    "id": 123,
    "name": "Jim Bloggs"
    "orders": {
       "href": "<link to you orders go here>"
    }
  }
}

With this your client would have to make 2 requests to get a customer and their orders. Good thing about this way though is that you can easily implement clean paging and filtering on orders.

3) GET /customers/123?fields=orders This is similar to your second approach. This will allow clients to use your API more efficiently, but I wouldn't go this route unless you really need to limit the fields that are coming back from your server. Otherwise it will add unnecessary complexity to your API which you will have to maintain.