News for hackers. Stuff that matters.
Re:Using HTML as the Media Type for your API by snorkel on Wednesday July 11, 2012 @10:17AM (#4229266)
JSON wins because it's easier to manipulate JSON data directly in your language of choice because the data is already in a usable structure. If you instead receive data as HTML, you have to read that data into some native structure before you can work with it, which is too much hassle just for the minor benefit of having the data be directly presentable in a web browser.

... and by the way what if like most web designers I don't agree with the HTML layout of the data? For example I don't want list items in a bullet list, I want them in sortable table or in a combobox droplist instead. Then I have to convert the data into some readable structure so I can change it's layout, which means reading the data into a Javascript object perhaps ... gee, I wish the API just gave me JSON output in the first place.

Re:Using HTML as the Media Type for your API by stanleydrew on Wednesday July 11, 2012 @12:04PM (#4229804)
"... which is too much hassle just for the minor benefit of having the data be directly presentable in a web browser."

The point is that this is not a minor benefit. You literally have documentation for your API built in. You don't need to write a whole set of docs listing what parameters are acceptable for which requests. You get the semantics of form handling and link-following for free. Having worked on an API that basically brings HTML form handling to raw JSON and XML (Twilio's), where we had to work hard to create documentation for what we were doing, I can tell you this is a big deal.

Incidentally, using a media type like HTML is the only way to build a true REST API. If more people understood that, we might be able to have a saner discussion around REST and its trade offs.

Re:Using HTML as the Media Type for your API by SilasX on Wednesday July 11, 2012 @12:17PM (#4229855)
>Incidentally, using a media type like HTML is the only way to build a true REST API.

That would definitely be a worthwhile point to consider, if REST didn't have several completely impractical requirements that people inevitably abandon the moment they try to make their site do anything more complex than (unauthenticated) CRUD.

Re:Using HTML as the Media Type for your API by stanleydrew on Wednesday July 11, 2012 @12:42PM (#4229983)
I don't disagree, I'm just saying that if we had discussions around REST that started with the assumption that you had to use HTML or something like it, then a lot more people would have a better idea of what REST actually is and could start to make more reasoned arguments about its costs and benefits.
Re:Using HTML as the Media Type for your API by SilasX on Wednesday July 11, 2012 @12:47PM (#4230000)
Maybe so, maybe so. But I seriously doubt that that's the reason REST advocates have a hard time explaining the benefits of being unable to use authentication (and attendant sessioning) under a literal reading of "no out of band info".

I'd have to say that the major impediment in that case is that there are no benefits.

Re:Using HTML as the Media Type for your API by AffableSpatula on Thursday July 12, 2012 @04:02AM (#4233558)
fwiw hal+json has documentation built in (arguably better than HTML does) and its browsable, here's an example API:

http://haltalk.herokuapp.com/

Re:Using HTML as the Media Type for your API by DougWebb on Wednesday July 11, 2012 @11:42AM (#4229705)
Just how much would this be different if the data was json?

   $("#listItems li", apiResponse).each(function() {
      $("#mytable").append("<tr><td>$(this).html()</td></tr>");
   });
Json or html, you're going to have to navigate to the list in the api response and loop over the list items to generate the markup you want.
Re:Using HTML as the Media Type for your API by untog on Wednesday July 11, 2012 @01:31PM (#4230237)
Well, for a start, you've assumed the presence of jQuery and the DOM. DOM parsing can be a pain to do server-side.
Re:Using HTML as the Media Type for your API by DougWebb on Wednesday July 11, 2012 @03:11PM (#4230872)
The article points points out that DOM traversal is annoying, but jQuery-like apis are available for most languages.
Re:Using HTML as the Media Type for your API by zafriedman on Wednesday July 11, 2012 @10:55AM (#4229468)
Last paragraph... hammer, meet nail.