Show webservices expose nested or flat lists?

Question

When designing a webservice, not matter if it's soap, xml or json: would you prefer flat or nested lists?

Example:

Nested:

<carRequest>
   <cars>
     <car>
       <manufature />
       <price />
       <description />
     </car>
     <car>
       <manufature />
       <price />
       <description />
     </car>
   </cars>
</carRequest>

Flat:

<carRequest>
     <car>
       <manufature />
       <price />
       <description />
     </car>
     <car>
       <manufature />
       <price />
       <description />
     </car>
</carRequest>

What's the advantage of one over the other?

Answer 1

There are advantages and disadvantages combined with personal style, tools (their default configurations, limitations or ease of use), need to support multiple MIME types from a single object representations, etc. I'm not going to go into all of that - since what works for some might not be a good solution for others - but I just want to point out a few things...

Which one seems more natural, the flat elements or the wrapped elements? How do people usually think about repeated elements? For example, <manufature>, <price> and <description> are wrapped in a <car> element. Why? Because they are related and together form a structure. Multiple <car>s are also related and form a structure too: a list of <car>s. It's more expressive in your representation and XML schema, and more readable. But of course now we go into personal preferences and wholly wars...

There is another advantage of the wrapped element. How do you express a list of cars that is empty versus a list of cars that is null?

If the elements are flat and you have no cars then what does this represent when you unmarshall it into an object?

<carRequest>
</carRequest>

Does your request have cars = null or cars = []? You don't know.

If you go with nested elements then cars = null is this:

<carRequest>
</carRequest>

while cars = [] is this:

<carRequest>
  <cars>
  </cars>
</carRequest>

And since you mentioned SOAP, you might at some point need to consider interoperability across technologies and tools (see Why is it important to be WS-I Basic Profile compliant?) which has rules on how the XML should look like inside the SOAP message. The style called document/literal wrapped pattern is preferred.

This is a broad subject and as a TL;DR I can only think of "choose your poison". I hope my answer is of help to you.