Data envelopes and format of `results` attribute
arowla opened this issue · 3 comments
Over on 18F/team-api1, we were having a discussion about whether to return results as an object or an array. We (@mbland, @monfresh, @jmcarp and @arowla) were generally in agreement that the results should return as an array. However, @jmcarp brought up the issue that the highest level of results returned needs to be an object, to avoid a JSON vulnerability2. To that end, we decided that team-api needs to wrap returned data in an envelope object and include a results attribute that is an array.
We'd like to suggest that the api-standards document should address JSON envelopes and result arrays in the "Just Use JSON" section3. Furthermore, the two existing suggestions to avoid the use of unpredictable keys based upon data, while returning results as an object instead of an array seem somewhat contradictory except in the context of a predictably-keyed JSON envelope, so making this recommendation directly would promote consistency and clarity in our API standards.
If this makes sense, I, or one of my Testing Grouplet teammates, will be happy to draft a PR with suggested changes.
Wow, that JSON vulnerability is something intense. I would like to add my 👍 for an outer envelope with a results attribute. Having worked/built APIs that return results, I usually regret returning just a top-level array because I eventually need to return metadata like the total number of matches or which page these results are from. Having a top-level envelope makes that simple, but it's ugly in an array. I'd like to suggest we also standardize the names for other common top-level attributes we might include so one array doesn't have page while another has page_num and another has page_no (I see a sample JSON with a pagination record in there, but maybe an explicit table too)
This could also go in as an augmentation of the Metadata section.
https://github.com/18F/api-standards#metadata
I'm not going to make a PR until we work out in #54 whether this repo will continue to be one page or many...
Seeing this reminded me that I wanted to talk to folks about community API standards, like JSON API: http://jsonapi.org/. If we're serious about making recommendations for API standards for our projects, we might want to consider adopting a standard that already exists, and has tooling and community support.