passivsystems
Could body-examples be a set rather than a vector ?
We currently grab the first entry in a few cases - this would not be deterministic with a set. e.g. which one do we display in curl commands?
I'm not sure it would need to be deterministic for curl command example purposes... or API docs... are there other cases where being deterministic is required ?
API docs should probably document all examples - not just first. But should the order be consistent?
IntegTests should be non-deterministic.
So the only case which I think should be deterministic is curl. Not sure if getting a different example each time you request curl examples is a good thing. Codex author may want to indicate one example as being the 'normal/default' case - the others are just possibilities, but with low occurrence. Maybe could be a set if we could indicate which is the 'default' example? I could be over thinking this, and it doesn't actually matter.
RE the API docs point there is an incoming ticket on that subject - I will try to get it linked to this one.
Agree with you on the IntegTests, so you are right... curl is the question. I am inclined to agree with you now, that reducing the number of surprises is a good thing, so it should be deterministic.
I think though that this determinism should maybe take into account another inbound ticket :-)
Just off to a meeting but will fire some more stuff in afterwards on the off chance you are intrigued :-)
As I promised in my previous comment... inbound information has arrived, please see #181 and #183.
Essentially we are starting to consider the concept of RESTful 'representations' where passing some information (perhaps a header) in the request can yield a response with a specific format.
This would be relevant to curl example responses, and a need for some work over the API doc output.
WDYT ?
When displaying curl examples, should we then provide one of each type of request which leads to a distinct response?
My first thought would be probably not, it is not the curl examples job to document the endpoint fully - jus t to provide a useful example... I think your suggestion of a 'default' in #183 would be something that could work.