3 ms·

"... 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 be

"... 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.

SilasX 14y ago
>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.
- stanleydrew 14y ago
  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.
  - SilasX 14y ago
    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.
AffableSpatula 14y ago
fwiw hal+json has documentation built in (arguably better than HTML does) and its browsable, here's an example API: http://haltalk.herokuapp.com/ http://haltalk.herokuapp.com/

SilasX 14y ago

>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.

stanleydrew 14y ago
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.
- SilasX 14y ago
  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.

AffableSpatula 14y ago

fwiw hal+json has documentation built in (arguably better than HTML does) and its browsable, here's an example API: http://haltalk.herokuapp.com/ http://haltalk.herokuapp.com/