My API has two records: Car and Account. An Account may have many associated Car records.
I have REST routes for updating deleting creating a car record.
Normally, a GET route for call for all cars would look like this: /car
A route for a specific car would be /car/:id the :id being from the Car.
How would I set up a REST route to get call cars by account ID? Would I have to do something like account/:id/car?
You can do it hierarchical with URI path or use querystring. The URI RFC covers this I think.
/cars?account=123
/accounts/123/cars
As of REST you can return a hyperlink with the upper, something like
{
"operation": "ListCarsAssociatedWithAccount(accountId)",
"method": "POST",
"URI": "/accounts/{accountId}/cars",
"params": {"accountId": {"type":"AccountId"}}
}
The REST client should know only about how to call the ListCarsAssociatedWithAccount(accountId) and the URI and body templates can be filled with the params.
With this approach you can even describe the body of the POST request and the expected response if you want to and automate it further:
{
"operation": "ListCarsAssociatedWithAccount(accountId, x)",
"params": {
"accountId": {"type": "AccountId"},
"x": {"type": "Number"}
},
"method": "POST",
"URI": "/accounts/{accountId}/cars",
"body": {
"q": {
"w": {"param": "x"}
}
},
"returns": {
"type":"CarList",
}
}
ListCarsAssociatedWithAccount(123, 5)
->
POST "/accounts/123/cars"
{
"q": {
"w": 5
}
}
200 OK
{
operations: [...],
values: [
{"carId": 34, operations: [...]},
{"carId": 3, ...},
{"carId": 4, ...},
...
]
}
->
var cl = new CarList();
cl.support(o.operations);
var item1 = new Car("carId": o.values[0].carId);
item1.support(o.values[0].operations);
cl.add(item1)
...
return cl;
Something similar (but a lot more complex) is used in the Hydra framework. http://www.hydra-cg.com/
The endpoints are consider flexible and cheap to add (and modify while preserving backward compatibility). But normally something like this:
GET/UPDATE/DELETE: accounts/:id/cars/:carid
GET(search)/CREATE: accounts/:id/cars/
and you could also get the same information from:
GET/UPDATE/DELETE: cars/:carid
GET(search)/CREATE: cars/
Note that on the backend, you should be using the same logic for both endpoints though (reusing code here between the endpoints). The idea of the first set of endpoints is that you can drill into specific elements in a logical/hierarchical manner. So if you needed some sub element of cars for a specific account:
GET/UPDATE/DELETE: accounts/:id/cars/:carid/wheels
That allows maximal use/reuse of data without the need to constantly add filters based on account/car in the various endpoints.
NOTE: normally the endpoints would be pluralized so that you can do searches from the same endpoint, so `GET /accounts' could include search parameters to gather result sets.