zalando/restful-api-guidelines

Clarify interaction of `fields` and `default`

Closed this issue · 5 comments

dehora commented

It's not clear whether the fields parameter is intended to have a default (at the level of design), or if it's intended to be used only to create partials from a whole. As things stand in the guidelines, it seems to not be an incorrect approach technically speaking. to combine the two so as to allow a resource using fields to return a partial object by default.The follow on implication is an API designer using these guidelines can require a client that wants to obtain a whole object to ask for every field at every level of depth.

tkrop commented

I think this is related to #483, because if fields is combined with default it pretty much renders embed useless. May be we should than focus on one rule for both aspects. I would favor fields than.

@meshcalero what do you think?

whiskeysierra commented

if fields is combined with default it pretty much renders embed useless

Can you elaborate on that?

ePaul commented

From the Guild meeting

Having a default value for the fields parameter is confusing, because as the result you won't get from the API whatis specified in the model, but just some subset of it, and first need to check the parameter's default value (which might even be different between endpoints) to figure out what's going on.

ePaul commented

To add to the guideline:

  • default value for this parameter is counter-intuitive, and should not be used

We also discussed whether it might make sense to make this parameter required, but didn't come to an agreement here. So for now we don't add anything about this to the guidelines.