

REST in peace, SOAP - mcgin
http://royal.pingdom.com/2010/10/15/rest-in-peace-soap/?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed%3A+RoyalPingdom+%28Royal+Pingdom%29&utm_content=Google+Reader

======
jmillikin
I will bet money that most of these "RESTful" APIs are nothing of the sort. In
almost all cases, when somebody says they're using REST, they're _actually_
using ad-hoc XML-RPC -- fixed URLs, non-descriptive content, etc. Ignorant
programmers have fixated on trivial aspects of some REST applications (use of
PUT/DELETE, "pretty" URLs) and ignored all the important aspects.

This sort of thing happens a lot in software culture -- see people claiming
Java or C# are object-oriented, that C++ is functional, that Python or LISP
are "scripting languages". It's cargo-cult nomenclature, and it disrupts
technical conversation to the point of uselessness.

Roy T. Fielding, who described the REST style, has an excellent blog post
titled _REST APIs must be hypertext-driven_ <
[http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven) >, where he lays out some ground rules for calling any given interface
a REST API.

~~~
tptacek
I find Fielding's writing on REST opaque to the point of unintelligibility.
This is a prime example. He actually _has an example_ of a HTTP/XML interface
he doesn't like... but he can't bring himself to talk in specifics, and
instead hews to academic jargon.

So, can you translate his bullet points for me? Or can I safely assume that,
yes, Roy Fielding doesn't believe these interfaces are "REST", but that I can
safely ignore that fact and use the term "REST" the way the rest of the world
does (RPC that uses URL patterns instead of WSDL).

~~~
jmillikin
\------------

 _A REST API should not be dependent on any single communication protocol,
though its successful mapping to a given protocol may be dependent on the
availability of metadata, choice of methods, etc._

A REST API should work over any protocol (HTTP, FTP, SSH, whatever) with
enough basic functionality to support it. It shouldn't mandate any particular
protocol.

\------------

 _A REST API should not contain any changes to the communication protocols
aside from filling-out or fixing the details of underspecified bits of
standard protocols_

A REST API shouldn't require a customized version of the underlying protocol.

\------------

 _A REST API should spend almost all of its descriptive effort in defining the
media type(s) used for representing resources and driving application state,
or in defining extended relation names and/or hypertext-enabled mark-up for
existing standard media types. Any effort spent describing what methods to use
on what URIs of interest should be entirely defined within the scope of the
processing rules for a media type_

Here's big idea #1. Documentation for a correctly designed REST API will
describe mostly _what_ is being returned, not how to get it. Each resource is
accessed via a different resource, except for the standalone root.

For example, you might start at the root resource <http://foo.com/api/> . It
returns, as content, a set of subresources that can be requested. The API
documentation should describe what data the server sends for /api/ -- what
format it's in (HTML, XML, JSON, etc), how to find its subresources (<a>,
<form>, id'ed elements), and any relationship metadata it contains. The user
agent (web browser) uses the MIME-type returned by the server to parse
whatever it returns.

\------------

 _A REST API must not define fixed resource names or hierarchies (an obvious
coupling of client and server). Servers must have the freedom to control their
own namespace. Instead, allow servers to instruct clients on how to construct
appropriate URIs, such as is done in HTML forms and URI templates, by defining
those instructions within media types and link relations._

Big idea #2: the API documentation shouldn't just be a list of URLs; if it is,
the server's URLs can't be modified without breaking clients. Clients should
use hypertext to parse URLs retrieved from the server.

For example, the front page doesn't just give you a list of story IDs and
require you to build the URL manually. It provides each URL in an anchor, as
an opaque identifier, and your web browser simply passed it back to the server
to get whatever it points to.

\------------

 _A REST API should never have “typed” resources that are significant to the
client. Specification authors may use resource types for describing server
implementation behind the interface, but those types must be irrelevant and
invisible to the client. The only types that are significant to a client are
the current representation’s media type and standardized relation names._

The client shouldn't have to contain a list of what URLs return what data. If
<http://foo.com/students/> returns a student list, either use the MIME-type
(application/x-foo.com-students) or a standardized relation name
(<foo.com><list rel="students">...).

For XML-based APIs, I would encourage the use of XML namespaces, although
Fielding doesn't mention them. Sometimes you've got a few dozen different
document types, and it just isn't worth figuring out MIME-types for them all;
in that case, return (application/xml) and let the client use the namespace'd
root element as an identifier.

\------------

 _A REST API should be entered with no prior knowledge beyond the initial URI
(bookmark) and set of standardized media types that are appropriate for the
intended audience_

This is mostly an elaboration of previous bullet points; clients shouldn't
have to hardcode a list of resource locations. If your client has something
like "students = Resource("/students/"), it's going to break when the server
changes that URL.

~~~
kaitnieks
The biggest problem I see with this is that in real life clients will hard-
code the urls anyway and break when the urls get changed.

~~~
beza1e1
Why is this the biggest problem? For every protocol there are broken clients.
For example, most XML parsers are broken. That is not a problem of XML, is it?

~~~
glhaynes
What's the alternative? For clients to refresh their copy of the "parent"
resource [there may be a better term for this... I mean the resource used to
access the resource that is to be gotten] often? For a commonly interactively
accessed thing, it would introduce a lot of latency for clients to get it
every time, so I suppose it must be cached... and then the cache of the parent
resource be refreshed regularly and in case of failure? How far up the tree
should that go?

In other words, if I want to get the Twitter feed for Joe's "ABC" group and I
don't want to hardcode the URL for that resource, how often should I download
(and cache), parse, and traverse the resources for Twitter's users then Joe's
feed then Joe's ABC group, etc.? Or am I misunderstanding this?

~~~
chrisbolt
In this case respecting HTTP's Expires: or Cache-Control: max-age= headers
seems like the thing to do.

------
tptacek
The story is very much the opposite in enterprise apps; I can't remember the
last REST interface I saw, but we see SOAP interfaces every week, in new apps.

Unfortunately, SOAP isn't going anywhere. It's just not popular with Internet
startups. Neither is ASP.NET.

~~~
kls
The problem is that the interconnected web of services are emphatically REST.
This is the next generation of enterprise systems and it is growing quickly.
One you adopt salesforce.com as your CRM strategy the next thing you want to
do is integrate that system of record into the larger enterprise system. While
Salesforce.com does offer SOAP services they in the end had to offer REST
based services due to overwhelming demand and while they support both my
observation is the the REST services are getting more attention (I don't work
for or represent Salseforce.com, so take that statement for what it is worth,
an opinion). If demand drops off it makes logical sense that the SOAP services
will be deprecated. Further there are some SaaS systems that do not offer SOAP
at all and that number is growing daily.

The enterprise of the future looks like an ESB that brokers data to and fro an
assortment of SaaS, with some core in-house systems in the mix. It makes sense
for companies whose bread and butter is not technology and places economies of
scale on the SaaS providers. Many of those SaaS are opting for REST only
implementations.

In a way it makes sense, for alot of the integrations you are wanting to pull
data from the system for analytics, trending and reporting along side an
aggregate of other data sources. REST make sense because it (loosely) acts
like SQL which despite it's problems is a good data manipulating language.

The thing about REST is that someone needs to come up with a uniform and
simple authentication and authorization mechanism that is seamless across the
board.

~~~
tptacek
The thing about REST is that executing on it involves understanding REST. The
thing about SOAP is that you can practically push a button in your IDE and get
a SOAP interface. No, the enterprise world is not about to transition to REST.

~~~
rubinelli
It's one button away... as long as you have the same technology on both sides
(and then, why are you incurring all this overhead anyway?) Maybe this has
changed in the last 3 or 4 years, but the last time I tried to get .Net and
Java stacks talking via SOAP was a royal pain.

~~~
masklinn
We're talking about The Enterprise here, this kind of stuff is not even on the
radar.

~~~
darklajid
I'm part of a 7 figure project right now. We're a .Net shop, they have a Java
infrastructure (and are as "enterprise" and process-laden as you can imagine
and then some). We need to integrate -> See, we're right there.

SOAP it is for us and I do have to say that I'm rather relaxed. For us it's
just one way (Java services, Java generated WSDL, we just consume/use the
stuff), but it works rather well.

Unless you don't know about 3.5/WCF/Service References and try to do it the
old-fashioned "Web Reference" ASP.Net way: That's a royal pain and just plain
doesn't work at all for some (valid) SOAP things (some sequences of
alternating complex types a la [Key, Value, Key, Value,...] for example cannot
be mapped). Guess how I found out..

------
devmonk
My guess is that this is overblown a little.

Rails apps make RESTful services fairly easy, even if it doesn't usually cover
the entire spectrum of RESTful actions. Many Rails (CRUD) controllers are
going to have 4 RESTful actions built into that one controller/service, so a
single app might have one RESTful service for each model (assuming it is
exposed).

SOAP has been overtaken for sure, but I think that first pie chart set should
show the _number_ of services, not just the percentage. My guess is that the
number of SOAP services may have grown, but the number of RESTful services
just grew much more quickly.

------
thecoffman
I have to deal with SOAP APIs at work (Google, I'm looking at you) and they
are seriously the bane of my existence. SOAP and the people behind it need to
die a slow, painful and lonely death.

~~~
viraptor
Can you explain why? I mean, sure SOAP has its problems, but is anything else
really that much better?

You move the action and some parameters into the request itself. You change
the representation from xml to json. You get rid of schemas and namespaces
(which makes the service either better or worse, depending on its size).
People seem to be very upset about SOAP wishing it death. What is it that
you're actually complaining about?

~~~
binspace
It's complicated, difficult to understand, requires large tools (expensive
ide's) to be productive with, different vendors have different interpretations
of SOAP anyways.

Basically, it's a bunch of extra work and requires more documentation due to
the complexity of it's implementations.

Also, SOAP libraries (e.g. Soap4r) are problematic (doesn't talk to
Micro$soft's version of SOAP properly).

REST is over HTTP. Just about all programming environments have a HTTP
library.

~~~
viraptor
Just playing a devil's advocate here a little bit, but soap doesn't really
require that much. For example for .net, you just run wsdl on some url and it
generates the interface code for you.

Also the complexity is needed when your size goes up. Even verifying that the
requests make sense is easier with schemas. Right now there is some project
for json-schema going on, but it's not crazy popular yet. SOAP can be self-
documenting too with its own structure mappings, type restrictions, etc. etc.

Don't you think it's only delaying the fact you'll have to reimplement the
same stuff at some point yourself (since json based rest simply doesn't
provide them out of the box)? (yeah - I know rest is protocol independent, so
you can have xml and schemas too, but majority of "rest" services just throw
some json and hope it sticks ;) - too bad if it changes between versions)

~~~
Roboprog
And how many internet startups are using VisualStudio.NET? (non-0, to be sure,
but they are the outliers)

And pay attention to the cross-stack arguments, to say nothing of the cross
_version_ differences.

You remind me of this guy on stackoverflow:
<http://stackoverflow.com/users/76337/john-saunders> \-- M.S. kool-aid,
yummie!

I am still waiting for any feedback (not from John, just in general) on this
question: [http://stackoverflow.com/questions/2194316/good-book-for-
wri...](http://stackoverflow.com/questions/2194316/good-book-for-writing-java-
clients-for-sundry-web-services)

I guess anybody who know how to do these would be out pillaging and plundering
corporate "america", not writing books :-)

------
jinushaun
Unless you're using a framework like .NET where everything is done for you,
SOAP is just too much trouble and complexity for simply data exchange.
Especially if you're trying to consume it from Javascript or Flash.

I'm not sure how much of the "REST" in the pie chart is true REST, but POX and
POJ is so much simpler and easier for cases where you don't need a full blown
strongly-typed web services interface.

------
adulau
What's the definition of REST? I'm tempted to say: "easy to use from the
command line with curl only".

------
borisk
SOAP has 50x the features of REST. Even most REST advocates will accept that
there are scenarios, where it's better to use SOAP. If you need complex
security, reliability, addressing, etc. why not let Microsoft/IBM/Oracle do
the dirty work?

------
rbanffy
No. I wish SOAP dies a horrible death.

~~~
jfb
God, yes. What a steaming pile.

------
KevBurnsJr
RMM (Richardson Maturity Model) provides a good set of criteria for evaluating
adherence of a web service to the Representational State Transfer
Architectural Style.

[http://martinfowler.com/articles/richardsonMaturityModel.htm...](http://martinfowler.com/articles/richardsonMaturityModel.html)

My guess is that 80% of those "REST" APIs are RMM-0.

------
aidenn0
Maybe I'm misunderstanding the pie chart in the article, but isn't it possible
to have a RESTful API implemented in JavaScript?

------
twidlit
Wordpress + Blogger API is still XMLRPC which feels icky to hook up into. :)

------
wanderr
Tired of all the pedantry surrounding REST, but hate SOAP? JSON-RPC FTW.

------
plq
i get the feeling that an important concern that prevents soap adoption is the
bulkiness of the xml standard that it's based on. i hope that the efficient
xml interchange standard will make that concern go away that.

solutions like thrift seem to reinvent most of what's been done with xml
schemas and other standards around soap solely on the grounds of performance.

oh and it's surprising that json-rpc is not in this pie-chart. pure rest is
not powerful enough to communicate a complex object structure.

~~~
tptacek
Seriously? You hope that SOAP survives, and switches from XML to _binary XML_?

I'm already gearing up to send cyborgs back in time to kill the EXI team
members on the off chance that standard takes off.

~~~
plq
um, yes?

the way i see it exi is to reduce the time to parse xml. but i'm not terribly
familiar with exi standard (draft) and would like to know what's so terribly
wrong with it.

so, care to elaborate?

------
thomasfl
Amen

------
calebgilbert
SOAP is the worst thing ever!

That is all...

------
avgarrison
+1 just for the title of the article.

