passivsystems
Vary body-example based on req param values (REST representations)
Perhaps something like:
:types {
:OurVar "(foo|bar)"
}
:vars {
"ourvar" {:type :OurVar}
}
...
:rsp {
:200 {
:body-example {
"ourvar" {
"foo" ["foo-template.json"]
"bar" ["bar-template.json"]
}
}
}
}
Is the purpose for sim behaviour? In which case, sim lib may handle it?
By handling the selection in the simlib, we're not coupling to enum types - we could select one on any relevant of criteria. Either we select the response directly by filename, or we will need to add labels to the examples. e.g.
:body-example {
{"foo" "foo-template.json"}
{"bar" "bar-template.json"}
}
The context for this was with the free out of the box sim (ie no sim extension created yet).
I'm not convinced we should overload the codex with sim behaviour - especially when this is just one of many possible out-of-the-box behaviours. We should try and make writing a sim-lib as easy as possible.
Unless you can argue that we're not just discussing sim behaviour, but also the real api behaviour. i.e. we want to document the coupling between inputs and response shapes.
You are spot on with that last comment... I was thinking we may want to document the concept of 'representations'. It may as you suggest be more suitable to do this sim extensions, but it should probably flow out into API docs which means the codex will need to have some idea of a link between elements of request shape and sample response.
I'm thinking scenarios like pass a header in and get a restricted representation back, for mobile consumption for example.
We probably don't want to over complicate the body-example notation for the majority of cases where this doesn't apply. How about attaching additional/optional influences to body-example selection - which would also allow us to extend if we find other cases. e.g.
:body-example {
"foo-template.json" {:var "ourvar" :val "foo" :default true}
"bar-template.json" {:var "ourvar" :val "bar"}
}
(I added default which may be useful to solve #180).
or maybe something similar notation to query-params, using a vector.
I think extending in something like this direction would be good... and yes as for your second point, would be good to be consistent with query-params syntax, fewer surprises.
Looking at this more recently I'm of the opinion that if you just want the simplest possible random or indexed selection by default we have introduced a significant config overhead at the codex level. I'm inclined to suggest a strategy for body response selection should probably be defined outside of the codex.
