I suggest we remove the recommendation to support multiple formats.
Supporting multiple output formats adds complexity to an API, and the benefits are not clear. As long as the API is producing information in a well-supported, machine-readable format, clients can be expected to write or use libraries that process it.
The added complexity is because it is non-trivial to "export" data to different formats without data-specific post-processing. Some examples:
Many formats use different case conventions: XML uses tag names like last-name, JSON uses field names like last_name.
Some formats allow different syntax. XML forbids the use of spaces in tag names, while JSON allows them.
Formats have varying levels of richness. XML allows tags and attributes -- JSON has no attribute equivalent. So, often, XML output in APIs doesn't use attributes, in order to support easy export to both formats. Similarly, it discourages use of spaces in JSON fields if XML is going to be supported. This pushes APIs to use the lowest common denominator of data representation, instead of taking full advantage of any given format.
Not all formats can represent the same kind of data -- adding a CSV format, for example, means jamming hierarchical data into a tabular shape.
Finally, multi-format zeal in Rails-world led to a security bug -- ActiveRecord's automatic parsing of various POSTed formats included YAML, and Ruby's YAML parser had a very bad security flaw.
Better to just pick a format, and stick with it. That's what most of the big APIs are doing these days, and it makes just as much sense for small APIs as big ones.
gbinal
commented
10 years ago
I suggest we remove the recommendation to support multiple formats.
Supporting multiple output formats adds complexity to an API, and the benefits are not clear. As long as the API is producing information in a well-supported, machine-readable format, clients can be expected to write or use libraries that process it.
The added complexity is because it is non-trivial to "export" data to different formats without data-specific post-processing. Some examples:
last-name, JSON uses field names likelast_name.Finally, multi-format zeal in Rails-world led to a security bug -- ActiveRecord's automatic parsing of various POSTed formats included YAML, and Ruby's YAML parser had a very bad security flaw.
Better to just pick a format, and stick with it. That's what most of the big APIs are doing these days, and it makes just as much sense for small APIs as big ones.