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.
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.
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:
In general I believe the topic of REST encourages elitist attitudes, cargo cults and un-pragmatic solutions, which I also touch on at:
and I still strongly believe message-based solutions promote better designs for SOA-style remote services:
It's JSON-RPC with an IDL grammar.
And here's his presentation on the topic: http://www.slideshare.net/royfielding/a-little-rest-and-rela...
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
Edit: I said "API", should have said "Protocol"
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?
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
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.
Edit: The first three sentences on the Wikipedia article are all you need to know.
> REST was initially described in the context of HTTP, but it is not limited to that protocol.
I hadn't heard of that, but it sounds exciting, partly because it's so self-explanatory.
<comment href="/comments/2398293">Text of comment</comment>
I don't think this is, in practice, a huge deal, because people don't write generic consumers of RESTful APIs. At some point you need to actually know what it is you're trying to do and code for it.
On top of that, with RDF or XLink or XPointer and whatnot there probably are standards for doing this kind of thing, but nobody knows them, uses them or follows them.
That doesn't quite mesh with my understanding. Some media types support hyperlinks, like HTML, which describe how links should be included (anchors, forms and link elements).
For media types that don't support hyperlinks, such as images, video etc; you can use the HTTP header Link (http://www.w3.org/wiki/LinkHeader).
Both these methods support the relationship attribute allowing you to specify the relationship between resources thus documenting the way clients should interact with such linked hypermedia (e.g. the HTML media type specifies that Link elements with the rel attribute should perform a HTTP GET request to the indicated resource).
In the example you gave, you could use a rel attribute like "comment" and link to the comments. RESTful clients could then follow the hyperlinks to the comments, knowing how to interact with them and what to do:
<link rel="comment" href="/comments/2398293"/>