[zafriedman]

If you're just going to send plain HTML over the wire, why are you going to even bother thinking at the level of abstraction that most developers (well, at least me) tend to think of when "developing an API"? I'll give you that it's a loose notion, but there's another issue. If you're building a non-trivial web application, how does sending HTML as a media type help you to decouple your data from the DOM? I believe the answer is that it doesn't. You could make the argument that decoupling becomes less of a necessity when you are providing more "fine-grained" access by controlling exactly what HTML is generated from the server at each endpoint. I say it could be argued, but I wouldn't argue it.

[jon_moore]

I think it's somewhat of a benefit to make the clients expect to do a little searching to find the data/links/forms they want to use--it makes them a little more robust and adaptable (I guess because they have lowered expectations!). Contrast this to a client dependent on an XML or JSON Schema. Yeah, that client is easy to write, but you've now locked the server into not changing its format or you've doomed the client to break when the server decides to change anyway. I'm shooting for something a little better.

You can't totally decouple the clients; they have to understand in some way the vocabulary the server is using, but you can do a lot to decouple them from the structure of the markup.