
REST – Epic Semantic Fail - alpb
http://mikehadlow.blogspot.co.uk/2012/08/rest-epic-semantic-fail.html?
======
lukev
He's got some good points about how people talk about REST and how it's not a
protocol.

But then there's this:

 _If I want to write a client to communicate with your REST API I’m in a world
of pain; there’s no serviceutil I can point at your API to generate me a
proxy, instead I have to carefully read your documentation (if it exists) and
then lovingly handcraft my client using low level HTTP API calls._

I would infinitely rather use a well-documented HTTP+XML/JSON/clojuredata
protocol. The thought of code generation based on WSDLs still makes me feel a
little ill even though I haven't done it in years.

~~~
reinhardt
Is there a consensus on why the SOAP/WSDL business sucks? Is it just a lousy
bloated implementation of a potentially good idea or it's the whole idea
that's misguided/unrealistic/foolish?

~~~
lusr
I'd like to know too. There are a lot of people here rubbishing SOAP without
explaining why. I've consumed, simultaneously with hundreds of other
developers from disparate teams, 100s of SOAP services across a number of
financial institutions and any issues I ran into had nothing to do with SOAP.
Generating code with SvcUtil is great and does what it's supposed to - and
nothing stops you from refining it or writing your own service clients.

I don't need to run service calls from the command line - I have version
controlled integration tests that I right click on and select "run", as should
every major consumer of serious services.

I don't believe SOAP web services are always the way to go (I've never used
any in my personal projects, preferring my own web API and/or a service bus),
but that doesn't mean it's not suitable for other problems.

What's often missing from these debates is defining what environment you're
operating in (legacy and dependant systems/platforms/interfaces, network
architecture, how much architectural control you have, user load, number of
developers, number of teams, release cycles, politics [what was the last big
budget item that was purchased to solve the current problem], timelines etc.).
Once you start identifying the environment details, some of the simplistic
unqualified suggestions people make in these debates seem naive and
ridiculous.

~~~
mythz
SOAP is fragile, bloated and slow. It goes against what the very essence of a
service should be, i.e. to expose functionality in as accessible and inter-
operable way as possible. The higher up the WS-* stack you go, the less
supported it becomes - eventually only the Big Enterprise frameworks from MS
and IBM support the complete WS-* stack.

WSDLs promote code-gen and as different SOAP frameworks have varying levels of
WSDL support, you often end up with broken + ugly code-gen when trying to
consume from different SOAP stacks. SOAP is also a brittle format where even a
small namespace change can break the entire request, this makes versioning (a
core part of evolving services) extremely difficult.

I generally prefer clean HTTP APIs with Cool URI's and JSON which is a much
faster, smaller, more versionable and tolerant format that provides a better
programmatic fit than SOAP/XML: <http://www.infoq.com/presentations/Heretical-
Open-Source>

------
robinhowlett
I think it's easier to understand his argument when you think about the
problem at scale. Consuming one API is meat and potatoes to most of us; with
decent documentation and the REST style largely being followed, API clients
can be created rather quickly.

However, if I asked you to consume 1000 "REST" APIs, this becomes problematic.
There is no agreement on representation, nor is there metadata available to
infer commonalities.

So what have people done? They've tried to introduce solutions from other
"protocols". As mentioned in the article, HAL attempts to introduce a
predictable envelope around the data, using links and embedded resources to
become so HATEOAS friendly.

However, there still are holes. How do I know what to do with links? The rel
can tell you only so much - back to the documentation we go. How about we
introduce a rel to a schema, like XSD, WADL or JSON Schema? Not many have done
that and even fewer enjoy working with them.

How about knowing if I can PUT or POST to one of these links? Well the API
could support OPTIONS request, but does this suit your data intensive mobile
app consuming the API? Not too snappy. We could list them out individually in
the representation (thereby replicating the HTTP design through
representation) but now the size of the representation is growing dramatically
just to support metadata that rarely changes.

OData, GData and even CMIS have all tried to take a stab at data communication
protocols. Yes, they bring solutions to some of these issues at the cost of
complexity and verbosity. Plus, they use use discovery endpoints. And they
still tend to fall back on XML over JSON because of use of Atom etc. And now
we are halfway back to SOAP.

How about the versioning issue? Should client be aware of representation
structure changes and adapt accordingly? Well WRML (<http://www.wrml.org/>)
tried to take that one on and all the best to you if you read that through
once and understand it, never mind implementing the actual clients and
servers.

As ori_b summarized "REST isn't a protocol, it's a protocol pattern". REST
can't fit all scenarios. But I think what's becoming clear is that no-one has
found anything better, just more specialized. So the days of auto-building
clients to consume APIs is far away.

I guess we'll just have to embrace the chaos and keep building snowflakes.

------
ori_b
His whole argument can be distilled down to "REST isn't a protocol, it's a
protocol pattern". True enough, but I'm surprised that this is news to anyone
working with REST.

Edit: I said "API", should have said "Protocol"

~~~
podperson
Actually I thought his whole argument was down to "REST isn't a protocol the
way HTTP is a protocol" -- look the "P" stands for "protocol" -- which (a) is
true in some specific technical sense, and (b) isn't important.

I quote: "This style has no agreed protocol." and "The core missing pieces of
any RESTful web service protocol are agreed standards on media type and link
metadata." OK, so what?

~~~
deno
> OK, so what?

Well, when you try to fill in the blanks you get one of these:

1) AtomPub, which is a relatively simple protcol but has very limited
application

2) oData/WSDL, which are powerful but complex

------
eevilspock
Here's what Roy Fielding himself has to say:
[http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven)

And here's his presentation on the topic:
[http://www.slideshare.net/royfielding/a-little-rest-and-
rela...](http://www.slideshare.net/royfielding/a-little-rest-and-relaxation)

A common REST debate is "When to use POST?". His thoughts on that:
<http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post>

------
lttlrck
REST's protocol is HTTP. REST isn't an API, but you can create RESTful API's.

Yawn.

Edit: The first three sentences on the Wikipedia article are all you need to
know. <http://en.wikipedia.org/wiki/Representational_state_transfer>

~~~
tripa
REST's protocol is not HTTP. Quoting the very page you linked:

> REST was initially described in the context of HTTP, but it is not limited
> to that protocol.

------
dggrjx
This parallels the beliefs of someone I know, who's working on providing an
answer to this in a true REST framework, complete with meaningful links, extra
metadata, etc. It's a WIP, but I'm sure he'd enjoy the conversation if others
are interested. <http://www.wrml.org>

------
NanoWar
So we HAVE the Google Discovery Service [1] that would be awesome if it could
be used with other than just google's APIs.

[1] <https://developers.google.com/discovery/v1/getting_started>

------
ams6110
So he wants to turn REST into SOAP? Personally, I'll pass on that. REST is
agile. REST is not about a ponderous, verbose, bloated specification for 5
things I want to do an 50 other things I don't need but have to take with it.

~~~
mapgrep
"It seems like I’ve been rubbishing the whole ‘REST’ project. Actually I think
the current situation is healthy. Monolithic ‘enterprise’ protocols like SOAP
usually end up being a bad idea."

------
sabat
I'm not so sure the OP's argument is substantive. I don't know whether Roy
intended that his architectural style, described in his thesis, to become a
loosely defined web service 'protocol', but we're not really making everything
up as we go along. A well-implemented REST API is far and away simpler to
understand (and easier to use) than a SOAP counterpart.

~~~
wanderr
That's a bit of a false dichotomy though. SOAP is a giant turd, but it's not
the only alternative out there. JSON-RPC is just as easy to understand as
REST, without all the pedantry.

~~~
fusiongyro
One advantage of REST, I don't know if it's especially meaningful in this
context, is that RPC mechanisms encourage people to think of remote calls as
local, but remote calls have a lot more failure modes than local ones do. REST
keeps you aware that you're dealing with remote resources the whole time.

