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.
Hey @Adam, the docs are very much a living document. We do our best to keep up with the changes to our APIs, but if you’re noticing missing info please make a comment on that article so we can investigate and make updates.
I know that’s not super helpful to you in the short term, if you want to post more specifics about your use cases we’re happy to try to brainstorm solutions with you.
In the case of the List module what we’re trying to do is build a table that will contain all the data that’s returned from the List endpoints. For the simpler modules (eg Calendar) there’s a pretty obvious 1:1 mapping between the JSON parameters that get returned and column names, but with something like layout_data it’s hard to find a repeatable structure that we can use to help determine the schema of our table. We have solutions in place that allow us to represent fairly complex stuff in our tables, but they’re pretty much all predicated on having some kind of structure to latch onto.
In terms of other specific examples, can you tell me more about the structure of the the personas array that gets return by the Blog Posts endpoints (among others)? Also, the widgets array that gets returned by the COS Page Publishing API, the imports array that gets returned by the Deals API, the interactions array that gets returned by the Social Media API… I’ve got a pretty long list! But if you could give me some ideas on the structure any of the ones mentioned so far I’d really appreciate it.
Any suggestions on this issue? What would you suggest if we aren’t able to determine the structure of a returned JSON object or array (i.e. it isn’t listed in the examples or the formal docs)?
