Data envelopes and format of `results` attribute about api-standards

[harrisj]

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)

[arowla]

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...

[jmcarp]

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.