Hacker News Reader

>> A RESTful API is discoverable

So is SOAP.

>> Developers understand HTTP

SOAP runs on just about anything including HTTP or even SMTP.

>> Our tools understand HTTP

SOAP doesn't care what the clients or servers are written in or run on.

>> REST keeps us honest

I disgree, you can change something in a JSON packet and the client will only know it broke when it's run. With SOAP, if your client uses a compiled language then you as a developer will know first before you give it to a customer to run, you can fix it then.

> So is SOAP.

No it's not. In theory, you can just consume the WSDL and have all the methods available to you, but in practice, there are huge and unbridgeable issues with interoperability. A C# SOAP client will have trouble consuming a Java WSDL, and so on.

> SOAP runs on just about anything including HTTP or even SMTP.

SOAP runs on top of HTTP but merely uses HTTP as a tunnel. All the stuff that should be in HTTP - the resource, the method, the data - is inside the XML envelope.

If you want to consume a SOAP web service, expect to get your hands dirty.

> SOAP doesn't care what the clients or servers are written in or run on.

In theory, no. In practice, interoperability is by no means a given.

> you can change something in a JSON packet and the client will only know it broke when it's run.

That's not really what I was talking about, but if you make a breaking API change in any system, you should have a way to do it so clients aren't caught flat-footed when their app breaks.

Neither REST nor SOAP inherently solves this problem, but REST does allow for custom media types that include versioning.

>> A C# SOAP client will have trouble consuming a Java WSDL, and so on.

I have had no issues getting a C# client on Windows to work with a Java SOAP server running on Tomcat using AXIS.

I even have an Android client talking to that SOAP server with no issues.

>> In theory, no. In practice, interoperability is by no means a given.

That's because it's contract driven, with REST any changes on the server in the API will not break the client's compile so you won't know it broken until the customer calls at 2 AM. Unless of course you have 100% unfailing testing processes.

>> if you make a breaking API change in any system, you should have a way to do it so clients aren't caught flat-footed when their app breaks.

Cool yes right, SOAP.

>> REST does allow for custom media types that include versioning.

If REST ever gets to that level of specification we will have SOAP.

> No it's not. In theory, you can just consume the WSDL and have all the methods available to you, but in practice, there are huge and unbridgeable issues with interoperability. A C# SOAP client will have trouble consuming a Java WSDL, and so on.

This is something I have a hard time understanding. Your hypothetical generic REST client will have a hard time understanding my HATEOAS, discoverable, fully REST-ified service, if it has no idea what the service is supposed to do contextually. If my 'blog' resource has links to 'metadata' and 'related' things, without knowing what those are, how does a 'generic' REST client do anything with them?

How is that significantly different than SOAP?

I would love to see an actual example of the difference, rather than abstract discussion, as this is the point I have the hardest time understanding.

The only difference between REST-in-practice-today and WSDL is that you aren't expected to map each network interaction to a single procedure call. This makes a number of things easier: cache the results, GET data across many different endpoints if you know the format, enable data and metadata extensibility through the payload, and follow hyperlinks if you know the link relation and target format.

The Facebook Graph API is a great practical example of this ease of use in practice: https://developers.facebook.com/docs/reference/api/

You're quite right that things like "related" and "metadata" link relations mean nothing if you don't know what those mean - they are hooks for future bits of agreement. The difference between REST and WSDL in the long run, in my opinion, is the practical composability of small bits of agreement (or specs). The Web Services stack (SOAP, WSDL, WS-*) has had a very difficult time composing a bunch of specs together as the kernel of their agreement is basically the XML Infoset. With the RESTful Web, the kernel is HTTP, URI, and MIME (for now), which has endured a number of extensions (Flash, HTML5, Atom/RSS, etc.) and evolutions (the rise of mobile devices).

Caching at the architecture level has caused more problems than it has solved. How many times have you heard the phrase "empty your cache, then try again..". Utterly stupid. This is an optimisation that should be implemented by the application designer as needed, and if it is within their capabilities.

Experience shows that your benefits are actually myths. A 'RESTful API' is not more discoverable, understandable and 'honest' than any conventional, local or remote API.

> Developers understand HTTP.

Actually, prior to REST, most developers didn't even know about PUT/DELETE/etc. which are key operators that RESTful services are supposed to exploit.

Most developers also have shockingly poor understandings of all kinds of aspects of the HTTP protocol (headers, which ones are important, semantics of the various verbs, pipelining, multipart MIME/server push/etc., they typically know at best a handful of error codes that make sense in a RESTful context...).

> With no background knowledge, a client can do a GET request on the root URL to get a list of resources with URLS. It's easy to dive right in and quickly figure out what is available.

Where is that specified for REST? I don't remember it from Fielding's paper, and I've seen plenty of self-described RESTful services that aren't even remotely discoverable.

More than that though, service discovery is a very old concept and not anything new that REST brought to the table.

> Where is that specified for REST?

I'll be the first to acknowledge that the REST specification, at least in Fieldings Ph.D. dissertation, is unfriendly. Here's Fielding trying to explain what he meant:

"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 (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations."

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

In general, this goes by the tortured acronym HATEOAS:

https://en.wikipedia.org/wiki/HATEOAS

And REST advocates wonder why people have a hard time understanding it.

> I've seen plenty of self-described RESTful services that aren't even remotely discoverable.

You're right. Most services that call themselves RESTful aren't. I think the REST movement itself deserves a share of responsibility for how widely REST is misunderstood.

> service discovery is a very old concept and not anything new that REST brought to the table.

What REST brings to the table is the ability to discover your way through a service with no required background knowledge other than HTTP - which will be the transport protocol in (almost) any case - and some common media types.

That's a navigable interface, not a discoverable one. This is one of the key differences between a hypermedia style interface and a traditional directory service. Navigable interfaces tend to be easier for people to find what they are looking for, but for automated service discovery, a directory service is far more straight forward.