search

microsoft / api-guidelines

Microsoft REST API Guidelines
Other
22.69k stars 2.71k forks source link

Add guidelines to prefer "flat" over "nested" structures #541

Open mikekistler opened 5 months ago

mikekistler commented 5 months ago

Nesting complicates the user experience and should only be used when necessary. We should add guidance to use flat structures unless there is some significant value to nesting, with some specific examples where nesting does add value and where it does not.

rkmanda commented 5 months ago

Should we deprecate the use of x-ms-client-flatten and get rid of any guidance around it? while still keeping the guidance to encourage flatter schemas?

JeffreyRichter commented 5 months ago

Pasting my comment from Teams chat: Well, getting rid of it now will probably break SDKs. However, I do not think that TypeSpec has an equivalent for flatten so breaking may happen anyway. For greenfield, services should design their schema as they want it and this is how it should appear to customers. x-ms-client-flatten was a bad idea; it makes debugging harder and it breaks json merge patch. We'd love to get rid of it but we prioritze not breaking customers who are using stuff that already GA'd.

mikekistler commented 5 months ago

I think we should deprecate the use of x-ms-flatten in greenfield services. As Jeffrey says, if it is already in place in a GA API, we'll just have to live with it.