

Designing HTTP interfaces and RESTful web services - janogonzalez
http://www.slideshare.net/Wombert/designing-http-interfaces-and-restful-web-services-phpday11-20110514

======
drawkbox
Atom and XML for represention? You lost me...

I think the reason JSON apis caught like wildfire was to get away from the
many pitfalls of over-architecture of XML in relation to SOAP,
attribute/element dichotomy, namespacing with multiple nodes for the same
value and general bulkiness. Parsing xml in javascript, scripting like
actionscript and more is being mean to your consumers where JSON becomes
objects they can use immediately. Are you making the API for your consumers or
Roy Fielding?

Granted Roy has helped me win many arguments and I am on board, it just takes
time for these things to catch or be able to be used 100% to the spec as with
any standard. I see REST more as a pattern much like the GOF patterns that
evolved from actual work to become patterns. But strictly adhering to patterns
or standards is not always business/market/product capable at the time.

I don't see being true to what I deem a biased view of what REST is over
making your api dead simple. Simplicity is missing more in software than long
term thinking. This is mostly simple but adding in the requirement for
representational view to be deemed 'REST certified' is a bit snouty.

RESTful on the client was only recently available so all this is evolving
(i.e. setting client headers and anything other than POST or GET wasn't even
possible until a few years ago consistently in browsers). I think the wrong
direction to go is to get too SOAPy about services. Most heavily in use apis
on the web still have to bend more RPCish because the market required it at
the time, with time things will move more towards REST now that it is possible
to perform a DELETE or set a header from more consumers.

If real programming standards weren't both academic and market based but
solely academic then we'd all be using Java to code up our SOAP generated
services which in term didn't work with other platforms like .NET services.

KISS prevails always and once again... JSON is a member. And I am down with
HATEOAS but what a bad acronym.

~~~
pornel
The presentation is explicitly about REST, not about pragmatic dead simple
solutions.

It even quotes Roy saying _"Many of the constraints are directly opposed to
short-term efficiency"_ and that most developers don't care about goals of
rest.

I think points you're making are fine, but they're acknowledged in the
presentation, so your rant is unnecessary.

I think the author did a good job presenting _actual_ (you can say academic)
REST, rather than a more popular and simpler to create "JSON-over-HTTP
database" pattern (which is fine, but shouldn't technically be called
"RESTful").

~~~
drawkbox
Point taken and I read the quote. But this was also quite adamant that if you
didn't do it certain ways it was no longer REST. I think that is a bad way to
present simplifying web services in REST and harmful. REST going mainstream
was great simply to move away from all POST based SOAPY services.

Do you really believe if you don't use Accept headers as the only means of
version that you aren't REST? Is REST a pattern you can follow only to the
letter of Roy Fielding's dissertation? If so there might not be ANY REST web
services out in the real market that are big. Everyone is just doing RESTish
or RESTy instead of certified RESTful.

Also I believe HN is a place where we can discuss articles and pragmatic
opinions about it, I don't assume everyone just agrees that this presentation
was the one and only way to do REST like the author was stating. I stated my
opinion to that. If this is the only way to do REST, simple services then the
whole web isn't doing it yet.

This turned out like a rag on REST which it is not. It is a rag on over
complicating and ivory tower architecture. REST should be about simplifying
web services for consumers as well. When you get to implementing your RESTful
service to support all clients, even with the current marke,t you will find it
doesn't fit everywhere.

A service should be liberal in what it accepts and conservative in what it
sends. The market deems when it is necessary to tighten the standards, right
now his interpretation of it is too narrow.

We need a new standard called SIMPLE: RESTish/RPC, HTTP based, simple
messaging (JSON/YAML), urls can be abstractions (in fact it is better to hide
your models in most cases except for an admin scaffold), consumer aspect based
routing (login, signup, myinfo) all the way from front end to service
abstraction. Accept and formats can be in headers first and fall back to url
based. Kinda like how systems like twitter, facbeook, 37 signals, etc do.

~~~
pornel
I suppose that boils down to prescriptivism vs descriptivism debate. I'm a
prescriptivist in that case: there's Roy's thesis that defines what he meant
by REST, and if an API (no matter how useful and successful) doesn't fit that
description, it should be called something else.

I agree we need a good word for those HTTP-but-not-quite-REST APIs. I simply
call them "HTTP APIs", but maybe SIMPLE, NoRPC or REST 2.0 will take off ;)

------
boucher
I disagree with the notion that api.twitter.com is a bad idea. URLs don't need
to be unique ways of locating a resource. An application designed around
HATEOAS doesn't even need to include the domain in the URLs it describes, so
you could make the same resources available with the same paths on both
twitter.com and api.twitter.com without changing the content of the resources.

This isn't necessarily the best design in the world, but you also can't ignore
the real world requirements of operating a site as large as twitter. I suspect
it would be more expensive (in many ways) for twitter to direct all traffic to
twitter.com and then route it internally based on the accept header.

Versioning on the accept header is, in my mind, the most controversial part of
"Hypermedia" API design. Custom mime types add a lot of complexity in the real
world, from both the client and server side perspectives. And yet, changing
the path in order to access a new resource has many downsides of its own.
There's also a question of scale -- adding a bit of new information to existi

~~~
drawkbox
I agree, I am a big fan of REST but what is with the notion that the uri can't
be more abstracted? api.twitter.com can be the same as twitter.com/api. They
are both resources and they happen to route to the same thing. Not ideal but
may be needed in evolving api as it grows like you mention.

------
tef____
as much as it says that in a fielding-style rest system the URLs and verbs are
opaque, he spends a lot of time nitpicking over the format of urls.

unless the resource in question is exposed as an endpoint, the url and verb
are handled by the link or form discovered by the client, and _invisible_ to
the client.

as for versioning - versioning the mime types is a useful thing, but it does
still make sense to use a different url if you are using different links and
forms to navigate the service.

