I have a NoSQL repository with two tables, Foo and Bar. Each Foo has some metadata and a list of Bar ids. Each Bar has some metadata.
I'm writing the API for retrieving a Foo and would like to provide the ability to specify whether the returned Foo contains either the related Bar ids or the related Bar objects.
For example, one could GET /foo/foo-id-1?resolve=false and receive the response
{
"id": "foo-id-1",
"metadata": {...},
"bars": ["bar-id-1", "bar-id-2", ...]
}
Versus GET /foo/foo-id-1?resolve=true and receiving
{
"id": "foo-id-1",
"metadata": {...},
"bars": [
{
"bar-id-1",
"metadata": {}
},
{
"bar-id-2",
"metadata": {}
}, ...
]
}
I'd like to do this because
- In the case that the client only needs the Foo metadata and not the Bar metadata, I can save a call to the repository to retrieve the Bar metadata.
- In the case that the client needs the Bar metadata included with the Foo, I can save the client a call by resolving the Bar ids to objects.
My questions are
- What should be the name of the parameter that provides this ability? I've named it "resolve" but is there something better (perhaps "projection") or a standard?
- Should the parameter be a flag, as I've suggested in the example above, or a string in case later more Foo children are added? For example,
/foo/foo-id-1?resolve=bars,bazs. - Is it ok to have an endpoint (GET on
/foo:id) that returns two different data schemas? That is, in the first case the data schema containsbars :: [String]and in the secondbars :: [Bar]