Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free.

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

We need to create an API to our system. How do I convince my boss that REST is a better option than SOAP (or XML-RPC)?

I say REST is...

  • easier to implement and maintain
  • not much new to learn -- plain old HTTP
  • lot of people have chosen it Yahoo ~ Facebook ~ Twitter
  • will be lot quicker to code

My boss says SOAP is...

  • richer and more expressive
  • it's all standard XML (SOAP, WSDL, UDDI) -- and so will be easier to consume
  • well standardized than REST
  • Google uses a lot of SOAP
  • it is important to adhere to SOAP standards than to create a custom XML schema in REST
share|improve this question

marked as duplicate by gnat, MichaelT, BЈовић, Kilian Foth, Dan Pichelman Aug 7 '13 at 15:40

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

@greengit - What makes you so sure that REST is the better option? – Joel Etherton Aug 8 '11 at 13:40
Do a time/cost analysis of both and present it to him. – Steven Jeuris Aug 8 '11 at 13:57
Do you have to serve XML? JSON is a lot simpler on both sides. – kevin cline Aug 8 '11 at 17:04
If I am both the producer and only consumer of a service, I prefer REST/JSON. If I am just a consumer and there is no ready-to-use library in my favorite language, I find using SOAP a lot easier, mainly because of the WSDL (can often be used for code-generation). – Jaap Sep 28 '11 at 11:52
WSDL is nice for asynchronous development between teams. – user1249 Sep 28 '11 at 12:12
up vote 59 down vote accepted

From a guy who's used both SOAP and REST extensively...

BOSS says SOAP is...

richer and more expressive

Anytime someone says a product is "rich" I want to become violently ill. I can't think of a more cliche comment to make about a technology or platform. Basically you're saying "I think this product is great, but I don't have any actual facts to back it up." I don't know what he means by "expressive" so I can't really comment on it...

it's all standard XML (SOAP, WSDL, UDDI) -- and so will be easier to consume

This is patently false. SOAP can be finicky, especially when you get into things like complex types and authentication headers. This is especially true when you start doing cross-language communication - getting PHP to properly consume and communicate with a .NET SOAP service that was using complex types and authentication was an exercise in keyboard-snapping horror that makes me wake up in a cold sweat to this day. REST is definitely easier to consume - you just provide the URL and done! You have your data! There are some drawbacks to this, depending on your needs, but for many web services this all that's needed.

well standardized than REST

It is "standardized" by the fact that it has a schema. That's it. Aside from that, you're still going to have to work with somebody else's data, which is never a picnic no matter what communication protocol you use. And REST has a standard - its called HTTP. It works pretty well.

Google uses a lot of SOAP

They used to use SOAP (they may for some products still, but not many). The majority of their web services are solidly REST-based. Here's a link showing that they abandoned a SOAP service in favor of REST.

it is important to adhere to SOAP standards than to create a custom XML schema in REST

This sounds like one of those comments made by superiors with limited understanding of the actual technology at hand. There will only be one part of the SOAP packet that is standardized - the message header, and the body wrapper. Everything in between is your own XML. You still have to create your own message. The message itself is not conforming to specific standard. It is still a serialized object or group of objects.

As a closing note, SOAP versus REST is a big topic, one without a concrete answer and you'll probably get different answers depending on who you talk to. In fact, I can't say for certain that in your particular case that REST WILL be better but I can say that your bosses arguments are weak and are indicative of a lack of understanding about the distinction between the two. I've used both technologies and my hard and fast conclusion is this: there is no hard and fast conclusion and, like so many other tech decisions, it depends on the needs of organization. The best solution, truly, is thoughtful research, an open discussion between the people working on the project to find the best solution, and an honest look at your needs.

Here a few links to existing discussions that may be beneficial.

share|improve this answer
@greengit Not to mention the case where your service provider changes platforms for delivery. Then the way you implement it may matter. – Lee Louviere Aug 8 '11 at 14:51
@greengit, don't forget to mark it as answered. – Kristofer Hoch Aug 8 '11 at 15:57
expressive: It has lots of useless metadata details built into the xml so it's both harder to read and maintain. – configurator Sep 28 '11 at 11:39
Ah yes, the horror of WSDL types! At least the OP is in charge of that, but they'd better make an inventory of the tools their customers are going to use to consume their WSDL. – Jan Doggen Mar 14 '13 at 7:37

SOAP or REST? Other answers do a good job of helping you argue the point from a technical perspective. However I predict a KO is unlikely simply because technically you could do most things with either approach. There are a the few exceptions that may lead to a technical knockout e.g.:

  • if API requests should be routable through external messaging middleware while still allowing the recipient to authenticate and verify the original sender, then SOAP wins
  • if you want to use your existing application's authentication and access control logic, then REST can be virtually a NOP, while for SOAP that can be a mini-project in it's own right.

If you don't have one of these exceptional requirements as a must-have, and since you are not the boss(!), I think the best you can hope for is a draw because although the decision appears "technical" it will remain subjective.

But .. if you want to make the best decision (and not just win an argument), maybe you can push to look at this, with your boss, in a different way:

Since you "need to create an API to our system", I'm inferring this is not just an internal technical detail of you system and "Technical arguments are for technical people -- aka, people who will be doing the work" doesn't apply. There's a group of people out there somewhere that will have to deal with whatever you deliver, and I think you would probably like them to use it and love it? If so:

What they need for the API probably trumps any arguments you or your boss can come up with (at least that's what they would think)

e.g. if they will want to integrate with your API via BizTalk or somesuch, then maybe SOAP it is (document literal and all). But if they are coders that will be writing to your API, SOAP may be the death knell for adoption, while REST will make you heroes.

If you already know who these people are, I reckon you should ask them what they need from an API. If it's a "new market", then maybe try to rope in the best representatives you can find, or at least try to describe and understand what the "representative customer environment" is going to be to help inform the decision.

In other words, I'd recommend you see if you can find the customer voice either from real external customers, or others in the organisation or partners who can do a good interim job pre-launch.

(then when they tell you "REST! Don't you dare give us some Rube Goldberg SOAP monstrosity", you can smile knowingly at your boss)

share|improve this answer
+1, it sounds like it is a customer requirement, not an internal technical discussion. – Jaap Sep 28 '11 at 11:54
agreed! don't ask each other - ask the people who will be using it. I've seen programmers go away for 6 months and bring back some horrible APIs, how it is used was not their problem. – james Sep 28 '11 at 13:02

It's a two step process:

  1. Convince your boss that the technical team should be the ones to chose the technical direction, not management.

  2. Chose REST. Or SOAP. Or POX. Or Whatever.

Technical arguments are for technical people -- aka, people who will be doing the work. Once the boss starts to decide the technology, you have a social problem. You need to convince your boss to get his hands out of the pie, and let you do your job.

share|improve this answer
It sounds to me like the boss has a technical background and does understand the issues, the OP just does not agree with his assessment. Many technical people move into management positions because they understand the big picture. I do not know who is right or wrong (it is rather grey) but I would not write off the boss as a Dilbert cliche. – dave Aug 8 '11 at 19:27
It doesn't matter if the boss has the technical chops or not; What matters is who is responsible for technical decisions. The boss may have all the information he needs to make that decision, but he's not writing the app. – Sean McMillan Aug 8 '11 at 19:30
The boss is responsible for the delivery of the product. If he is not technically minded, then he should rely on the assessment of those who are. If he is technically minded, the he should contribute his knowledge and experience to the assessment. Either way, he needs to be involved in the decision - that is his job. I have personally seen many projects where the coders just want to do something that is new, fun or pad their resume. I have seen this as a developer, an architect and as a TL. A competent boss is one who can see the big picture and make the best choice for the project/company. – dave Aug 8 '11 at 21:19
@dave, The Strongest teams have a technical lead who is a Sr. Dev (on Dev Team), or Sr. Engineer (Ops Team), who provides that technical assessment to the manager. Then the manager makes the business call, which if you have the right lead, you trust them with your reputation. Its just two very different skill sets. If a Dev only sees mobility in becoming management, your managers are either very napoleonic.... OR they just happen to be the most Sr technical Lead... but only for now. – TechZilla 2 days ago

I would propose a test: code two solutions that do the same very simple service. Use SOAP and a REST-ful API and compare the results. Given the toolsets today there should not be much of a difference. You can stand up a service fairly easily.

Next change the API. It is my experience that a developer changing a REST API can easily make the changes because they are dealing with a conceptual protocal that they understand. It is also my experience that the SOAP API will rely on tooling to accomplish anything. You can do it by hand but very few people do (for obvious reasons) once you see code/markup that is generated.

Better yet...have your boss do the SOAP implementation.

share|improve this answer
+1 for prototyping each to produce solid discussion. – nicodemus13 Mar 14 '13 at 11:19

You should look at the different environments, where your system is used and if these environments do inter-system communication mainly in a restful manner, than your system should offer such a interface as well. (Meaning, if your customers use it, than your system should do it as well.)

share|improve this answer

Instead of getting into the perpetual boss vs coder arguments let's take some specific cases and assess the suitability of the model. REST lovers are most welcome to refute with logical and fact based arguments -

Purpose: Remoting of services / beating firewall restrictions / binding with protocols such as HTTP

Options: SOAP / REST (discarding protocols like RMI etc as that's kind of out of context)

use case 1: I need optimized binding (JMS / RMI) for several reasons such as a) Transaction context propagation b) large payload exchange c) Stringent QoS Here, my choice will be SOAP. I saw someone mentioned about interoperability concerns with complex types - please explain why do you think WS-I basic profile compliance can't solve for your problem (with example preferably).

use case 2: I need identity(assertion) propagation in a federated environment of trusted intermediaries (active or passive). This is a B2B use case. I don't think I have a defined way of attaching policy with a REST endpoint. Hence SOAP based service becomes the obvious choice

use case 3: I need a management API for my PaaS. JMX mbeans are to be exposed as services. This is kind of point to point in nature. Bandwidth is a constraint. Governance is not a concern. Browser based client makes it more usable. HTTPS is good enough in this case, I'm not going to have to worry about message level security. I'll have a pick on REST as I don't need the niceties and complexities of SOAP in this particular case.

use-case 4: I need reliable message support. WS-RM can solve for this. SOAP is the obvious model here because the SOAP engine/ app server has OOTB support for WS-RM configuration.

use case 5: I need to invoke multiple endpoints in a TX context and HTTP is the only available option for transport protocol. I don't think REST supports WS-AT hence I go with SOAP

use case 6: I need an async endpoint. I don't want to unnecessarily hold up the requesting thread. SOAP will be the choice.

use case 7: I want to do away with the unnecessary overhead of XML to types conversion as the data will land up on a UI anyway with minimal or no transformation. REST with JSON would be my choice.

In general, If I'm thinking DATA/RESOURCE I'd prefer REST If I'm thinking operations/ methods (sync/async .. state..message level security..scalability) I be inclined to use SOAP

Let me not bring in the governance and SOA angle here. I aft'll don't want to sound like "one-of-those" in a forum dedicated to developers.

Feel free to correct me on the above ..

share|improve this answer

One of the important benefits of REST which hasn't been raised, is that it's cachable and easily scalable. SOAP is not cachable, as it is a POST request.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.