Some of the API docs, for example List layouts, provides info about the “first layer” of the response, but no data about the structure of anything deeper. For example, List layouts tells us that layout_data is “A complex JSON structure with the actual data for the layout”. However, it doesn’t tell us anything about the internal structure of the layout_data object. Does it have a set structure? What do the internal fields represent?
In general, there are many cases where JSON objects/arrays are returned but the docs either don’t mention them at all, or just offer a one sentence overview of what the object/array is (another example is the Widgets object returned by the Pages module). Further, these objects are often returned as empty when the example URL is hit. It’s very hard to know how to handle these objects if we don’t know anything about their structure, and in particular if it is regular or irregular. If an object has a set structure I want to add code to handle it based on said structure, and if it doesn’t have a set structure I’ll handle the object differently. At the least, if the docs could say something like “this object/array stores XYZ objects that represent … and have no set structure” or “this object contains PQR objects. PQR objects have the following schema:…” it would be very helpful. As it stands, I find myself trying to guess at the schema of many objects/arrays based on the example response which is both time consuming and error-prone.