brmore brmore - 20 days ago 6
JSON Question

Recommendation for documenting JSON API?

Are there any accepted standards or best practices for documenting a set of JSON API's? Done a fair bit of searching around and there seems to be a bit of a mish-mash of style / formats.

Maybe making too big a deal over this ... at some level docs is docs, but figured I'd ask.

Answer

The only common way of doing this is to give examples of the JSON returned. This works fine for simple JSON that does not have too many variations and is not too deeply nested.

For more complex JSON I recommend you look at the proposal made in the question Syntax for documenting JSON structure I think the "Taycher JSON Grammar Form" (TJGF) is a nice way to document complex JSON in a way that is easy to read and is in keeping with the lightweight spirit of JSON. It needs some extensions to handle alternatives and optional elements, but that should be straightforward to add.

Comments