![php[architect] logo](/wp-content/themes/phpa/images/new_logo_mark_nav.png){kind=logo}
What Will Power the Future of the Internet: REST or SOAP?
I was recently asked why we chose REST over SOAP for our re-write of the FoxyCart.com API, and the short answer that immediately came to mind was, “Because I don’t hate myself”. To expand on that answer, let me give you a little bit of the back story.
FoxyCart was built from the beginning with a desire to integrate with existing systems and avoid duplicating data. We’re not a CMS, we don’t do inventory tracking, customer mailing lists, accounting or analytics. We integrate with the tools you already use. As such, it’s critically important that our data be easily accessible in a way that makes sense. As a tool built by developers for developers, we want to keep things simple without creating “yet another thing” for you to learn or another manual to squint at while building your integration.
As we began our API re-write, we kept these ideas in mind. We didn’t go with SOAP primarily because it doesn’t keep things simple. I’ve worked with SOAP in PHP, Java and ColdFusion (yes, thank you, your sympathy is much appreciated). Granted, it is pretty neat to fire up a tool like soapUI and have a bunch of methods and stubs built out automatically or to see Eclipse parse a WSDL and show you that nifty drill-down-forever interface which exposes the depth of possibilities for the API. However, the real frustration I’ve always had is having to re-learn things I should already know. How do I create something, get it back again, make some changes or delete it? At the most basic level, most method calls can be boiled down to representations of data that just need to be manipulated.
Instead of having to dive into the SOAP API developer’s thought process (often leading to a DailyWTF moment), REST eliminates the confusion all together. Where a SOAP API may have methods like getAllSubscriptions() or customerSave() or filterTransactions(), REST allows us to say, “Here’s the representation, you already know what to do with it.” Ideally, if you’ve integrated with one REST API, you understand them all: GET, POST, PUT and DELETE. We’re all familiar with this thing called the World Wide Web, and it has scaled pretty well over the years following these simple patterns.
The story doesn’t end there. One of the other main reasons to be excited about REST is that it’s still, after all these years, actively being developed and discussed. The API Craft Google Group, as an example, is incredibly active, and they’re not just debating what Fielding really meant in his dissertation over a decade ago. They are helping each other build things right now. Companies like Apigee are creating great content on their blog, educating and improving the entire ecosystem.
New solutions are being proposed such as the PATCH HTTP method for partially modifying a resource. We’re still learning what Hypermedia as the Engine of Application State (HATEOAS) really means. There are plenty of questions like how hypermedia should be represented in JSON or how a client should interact with vendor-specific content types and what code-on-demand can do for you. These questions might seem overwhelming, but for us they are exciting! We believe the future of consistent, powerful API development is being defined right now, and we get to be a part of it.
If Facebook, Amazon, PayPal and Twitter have taught us anything, it’s that building a platform is more powerful than just building an application or a website. APIs are the bones of any platform. REST is the muscle that will get the job done.
***Image courtesy of Delyn Simons, Mashery API Network
Leave a comment
Use the form below to leave a comment:
Responses and Pingbacks
February 28th, 2012 at 6:24 am
I’ve just started a training “Oracle SOA Suite” at Oracle and I have to say I’m impressed with the posibilities. In the middleware stack it can make a lot of sense, especially in business environments where there’s always someone wanting for control.
Where it doesn’t make sense however is on the open web. If you need anything that requires a lot of explaining, as WSDL web services often do -the horror I faced in one of my academic courses!-, it’s pretty much failed for the open use. You need stuff that you can play with, enable even the worst of PHP developers to get it going, to have any chance of success. REST can provide this for the consumer. You can start harrassing the webserver within minutes without a college degree.
As the producer however I’ve never really understood REST fully, let alone HATEOS, even after reading the famous disertation (which is a b*tch). I’m ashamed to say I once sold a service as being REST-enabled but I’m still not that convinced that is completely was, never heard complaints though 🙂
February 28th, 2012 at 10:13 am
True REST does not work in most real life task. “True” means “you can only CRUD objects”.
The first challenge is batch operations, the next is service – “give me a sum of 2 numbers”.
REST works ONLY if the server is nothing but RDBMS. Because of this there’s no so much REST implementations what are true RESTs.
February 28th, 2012 at 2:27 pm
@NIels: you’re not alone when it comes to trying to understand REST, Hypermedia, and HATEOAS (could we get a worse sounding acronym?) But, there is hope out there. There are some really smart people that are doing the work to come up with some conventions and standards we can agree upon which I think will make for some really powerful, flexible APIs that are not tightly coupled between the client and the server. I just posted a couple days ago about some REST resources you may find useful: http://bestoked.blogspot.com/2012/02/restful-resources-required-reading.html
@dsa: Apigee.com’s blog has some really good posts about that. You can do calculations if you need to, but often it’s just a shift in mindset. Instead of thinking in verbs, when we think in nouns, things just make sense. That’s my take on it, anyway. REST has worked rather well for the Internet because humans are the ones making the decisions on “what to do next” with the hypermedia they are shown. I think as clients get smarter, they will also start making those decisions.
March 2nd, 2012 at 11:42 am
Btw, if you’d like to hear more about our story of building a RESTful API, please join us at tek12: http://tek12.phparch.com/talks/#From-POX-to-HATEOAS-A-Real-Companys-Journey-Building-a-RESTful-API If you make it out, come find me and say hello.
March 3rd, 2012 at 7:22 am
I couldn’t live without SOAP.
As somebody who’s job is mostly creating and working with APIs both in house and third party there’s one thing with SOAP that you never ever get with REST in the real world. That simply is it is *impossible* to change a SOAP API without publically documenting it (in the WSDL).
With REST sure APIs and changes should be documented, but the thing I’ve always found is they very rarely are. We can sit all day talking about the companies involved and the theory but the point is with SOAP it is just simply impossible. And that’s a good thing.
Most people’s hatred of SOAP I usually find comes from a lack of understanding a reasonably simple subject.
March 7th, 2012 at 2:10 pm
Great comment, streaky. Some of the REST proponents I’ve been dialoging with would argue how REST doesn’t need to be documented because the changes (if done right) don’t break existing clients. For example, when a web page changes their content, the browser doesn’t have to upgrade to a new version (usually) in order to show that content. There’s a loose coupling between the client and the server. With code on demand, the server could offer new features that the client could seamlessly support.
You’re right though… in the “real world” this may not always be done correctly. REST says people should code to the hypermedia and the media types, but that doesn’t stop someone from coding directly to a URL pattern which may break in the future.
I’m not so much a SOAP hater, I just prefer an API that intuitively makes sense instead of having to read a lot of documentation.
Again though, great point about the documentation having to be accurate since it’s what actually drives the API. That should be listed as a strength for SOAP, especially for those who like documentation.
March 22nd, 2012 at 5:50 pm
That choice is not a simple thing, REST and SOAP are two different architectures.
SOAP is protocol over the HTTP while REST is HTTP.
SOAP has a lot of good things, but I believe that REST solves 99% of our needs.
In my company we use SOAP based webservices, cause the WSDL document makes it easier to our clients.
In order to make it easy to build the WSDL I’ve created the EasySoap Project (https://github.com/lcobucci/easy-soap). It’s not a big deal, but helps a lot.
Sure it can be improved. I hope it may help someone.
July 9th, 2012 at 11:52 am
According to http://spf13.com/post/soap-vs-rest there is space for both, and there are a few cases in which SOAP would be required, including bank transactions made from an iPhone app.
July 18th, 2012 at 7:37 pm
I have been using SOAP for almost 10 years so I have a lot of good and bad things to say about it. It is much easier to work with SOAP nowadays since XML parsers have improved and we have moved towards UTF-8 as a standard character encoding method. REST, however, is much easier to implement and support and since so many services are now using it, it is inevitable that is will become the new standard moving forward. That does not mean SOAP is useless, but it will be sort of like Perl versus Ruby.
January 4th, 2013 at 11:34 am
Again though, great point about the documentation having to be accurate since it’s what actually drives the API. That should be listed as a strength for SOAP, especially for those who like documentation.
January 4th, 2013 at 11:35 am
True REST does not work in most real life task. “True” means “you can only CRUD objects”.
The first challenge is batch operations, the next is service – “give me a sum of 2 numbers”.
REST works ONLY if the server is nothing but RDBMS. Because of this there’s no so much REST implementations what are true RESTs.
May 23rd, 2013 at 7:15 pm
Lookie here, yes “lookie here”! SOAP has a contract and REST does not. I think SOAP is great because all I have to do is point my favorite SOAP framework (AXIS2) at a WSDL file and BAM, here is the code and everything I need to know about “what to pass”. REST does not have this! Another thing, let’s look at the more complex REST services like AWS. Why do they have there own java wrapper API around there REST service, because its a pain to call it using something like jersey. There is the rub, with SOAP the code is auto-generated for me and with complex REST services I get a jar file written by the vendor to use. Excuse me, whats the difference? Use the same programming model (like AXIS2 produces or any other SOAP client framework) to execute some remote function or download a jar file from the vendor. I am really looking forward to any work and the promotion of WADL, this is a kind of WSDL for REST. So, in the end, whats the difference? I really enjoyed reading this blog, thanks!