JSON Attributes of Petition Resources Should Be Explained Similarly to INDEX Operation

[BigSauce]

The We the People API documentation needs to include documentation explaining the attributes of a petition resource JSON object, similarly to how the INDEX operation's arguments are documented with their name, type, and valid values.

One reason this is important is for cases where it is impossible for developers to guess all enumerative values for an attribute in order to handle all expected states.

For example, it is difficult for developers to deduce all possible values for a petition resource's "status" JSON attribute. Within the "Resource: Petitions" section of the documentation, the "status" attribute should be listed, along with every other JSON attribute of the petition resource. The "status" attribute documentation would ideally include all possible values which We the People API may return and a brief explanation about the correlation between the possible "status" values and their real-world petition counterparts (e.g.., " 'responded' would be returned if the petition has received an official response from the White House").

Below I have listed an example of what this would look like.

The We the People API documentation would list every JSON attribute, along with:

1. argument name
2. data type
3. an explanation of what the argument is
4. valid values for the argument, for arguments which have enumerative values (e.g. petition 'status' attribute would list: 'responded', 'awaiting response', 'open', and I would list the rest, but the documentation hasn't revealed all possible values....do you get where I'm going with this?)

string status Represents the status of the petition. Possible values returned for this attribute are 'responded', 'awaiting response', 'open', and [any other valid values of which I am unaware]

[welschp]

Thanks, good flag - we're in the process of sortign through all of the issues/requests that came out of the last hackathon, will see about getting this into the queue.