To organize it hierarchically, you have the option of using URI paths or querystrings. This concept is covered in the URI RFC.
/cars?account=123
/accounts/123/cars
When following REST principles, you can provide a hyperlink for reference, such as:
{
"operation": "ListCarsAssociatedWithAccount(accountId)",
"method": "POST",
"URI": "/accounts/{accountId}/cars",
"params": {"accountId": {"type":"AccountId"}}
}
The REST client only needs to understand how to execute
ListCarsAssociatedWithAccount(accountId)
, while the URI and body templates can be dynamically populated with parameters.
This method also allows for description of the POST request body and expected response, enabling further automation:
{
"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;
A similar (albeit more intricate) approach is utilized in the Hydra framework.