In my experience, the biggest win is that it helps me as a developer to create clean interfaces. Whereas a homerolled RPC solution would encourage me to write controllers for different paths, taking arguments in various ways, when writing a REST interface I can create some kind of object:
{
index: function (req, res) { ... }
create: function (req, res) { ... }
retrieve: function (req, res) { ... }
update: function (req, res) { ... }
delete: function (req, res) { ... }
}
And then map that whole resource under a certain path, "/resources".
Further, it is built on sound principles such as, you can't destroy or change anything using GET, you can issue requests other than POST any number of times and nothing will go wrong.
Other things like using HTTP headers to decide in which format the consumer wishes to consume the resource, HTTP status codes for error handling, and HATEOAS, gives me the feeling of working with the system instead of building cruft.
I argue that REST in fact makes it easier "to maintain and implement the web services". YMMV.
* A RESTful API is discoverable. 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.
* Developers understand HTTP. REST is essentially just HTTP, and we already understand HTTP. REST means the API developer doesn't need to waste time and energy (badly) reinventing/re-implementing what HTTP does on top of HTTP; and the client doesn't need to waste time and energy learning a bunch of ad hoc protocols.
* Our tools understand HTTP. Just about every client language/framework on earth already understands HTTP. Without jumping through any extra hoops, a client working in Python or Ruby or C# or Java or JavaScript or PHP or even VBScript can execute an HTTP request on an API resource and understand the response.
* REST keeps us honest. A RESTful API architecture forces the API developer to be clear about what is a resource and what methods clients can execute against each resource. This makes for a better-organized, more orthogonal API.
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.
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.
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.
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.
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."
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.
Theoretically if done correctly then your REST service can be accessed by generic REST clients that don't know about your particular service.
Though generic client isn't going to know really what to do with your service. Aside from performing basic CRUD operations, a generic client would have no understanding if what any of it actually means. But, for example you can use code libraries that are designed to work with REST services in your client and not have to write as much boring "plumbing" code.
Though generic client isn't going to know really what to do with your service.
This is where hypermedia comes in. A rich set of standard media types allows your generic client to do useful things without knowing about any particular service.
Each of the constraints brings some advantages to the system. To me, the most important is the decoupling of the client from the server.
I think this doesn't seem that important because we still code each client against particular API, but we could adopt true uniform APIs - by not only using the HTTP methods and following HATEOAS, but by also standardizing on data formats that are widely adopted¹ - we would be able to write much more generic clients that could work with different APIs, perhaps even with ones not considered by the developer, without wasting hours upon hours writing code against each service.
¹ No, JSON isn't a standard data format, but more a standard serialization format. You still have to manually code against each service's response types.
For me, it's just a helpful description. I know something about an API if it's RESTful, and I know what others expect from me when I say it. And practically, Backbone.js expects REST conventions from the server API, which is a (small) gain in setup time.
I'm currently working on a project where the WSDL is broken. The Java application that constructed the WSDL was unaware it was running behind a HTTPS proxy. This led to it importing HTTP URLs that didn't actually work.
The solution was to have Suds re-route specific URLs to resolve correctly. The fact that Suds is designed this way is testament to his common this problem is.
Yes, you can get HTTP servers that don't respect the safety of Get, but it's a much less common issue.
I run my Tomcat server with AXIS providing SOAP capabilities on localhost:8080 and front-end it with Apache using ProxyPass and ProxyPassReverse.
My SOAP web app runs fine, my Android test client also hits it with no complaints.
My Apache server can be hit with both HTTP and HTTPS which lets me use Apache to handle certificate management while I cna run any type of app server on localhost that I want.
So far no issues with this scenario. I used this for a contract I was just on and it also worked fine for both the SOAP and REST clients.
I can appreciate making web services a lot simpler than horseshit like SOAP. If all we want to do is get data in and out, let's do it simply and without a bunch of extra ceremony. I can appreciate the notion of using concepts we've already had forever in HTTP rather than reinventing them, poorly.
Beyond good common-sense things like this, REST seems to involve a lot of people yelling about whether something is or is not REST.
Confession: I don't understand what the advantages are supposed to be. I want to believe it isn't just arbitrary dogma. I really do.
Applications don't care about the method or protocol a web service is using. Just get the data to and from.
Humans should care about how easy it is to maintain and implement the web services and anything they choose to do to make that goal a reality is good.
Oh, it makes for cute looking URIs, I guess.