Short answer, REST. Don’t make your engineers and clients suffer by making them deal with SOAP/XML/WSDLs. Who doesn’t love acronyms? You don't want them to curse you, so make their lives easy. I know the idea of soap is clean and refreshing, but nothing in dealing with SOAP makes me feel clean or refreshed, only dirty and exhausted. And yes, this topic has been widely covered but Cloud Elements prides itself on being the lynchpin of APIs so I figured we should probably have a post on this topic. Don’t you feel lucky?
Let’s start with SOAP. I'll keep this as unbiased as possible, but if you've read my other posts you'll know that will last about 30 seconds. SOAP stands for Simple (HA!) Object Access Protocol. Its format is that of XML, which resembles that of HTML tags, *gag*. Well I tried to keep it unbiased, that didn't last long at all. SOAP was developed back in the 90’s and thus is used in many legacy APIs. It is a stateful operation and is awesome if you care about all the changes to a given object, not just THAT it changed. Who doesn't love all the data? Your ISP and the host server. That amount of detail can decimate your bandwidth. SOAP is a standard as well. Meaning that there are rules to follow. Where as REST is a set guidelines left to be interpreted by the given engineer.
RELATED POST: WHY JSON IS BETTER THAN XML
Now, it doesn't seem fair to just demean SOAP entirely. Though, personally, I like REST, SOAP has some advantages. Since SOAP supports WS-Security, it offers more robust security. Want to more easily deal with Firewalls? SOAP’s standard HTTP protocol makes firewalls become less of a hassle. Do you need ACID-compliant transactions? Well better learn to love XML, SOAP is the best/only option for this.
XML:
Now for the newer arrival, REST. REST stands for Representational State Transfer. It gets to use the easier to understand and write JSON format. Because it does not hold state, just like the rest of the web, it takes far less bandwidth. Hence why your mobile apps are almost entirely developed on the REST principles. I say principles because there is no standard. Just some guidelines. Follow them or don't, your call. SOAP requires you to follow a rigid format and protocol. Because it is more a guideline and uses JSON you can learn, and deploy it much faster than SOAP/XML. REST also uses the standard HTTP verbs (GET, POST, PATCH, PUT, DELETE). So if you’re already familiar with those and understand how to write JSON, you’re basically 99% of the way to writing an API.
REST:
So that’s the basic breakdown. Fine, SOAP has some upshots. But those are outweighed by its legacy status, glutenous bandwidth needs, and XML format. If you are starting from scratch, building an API consider that something like 70% of the web is now based on REST/JSON. Write one API endpoint in REST and another in SOAP and let me know where your sanity stands after each.
If you want an overview of JSON v. XML (and I know you just can't wait for that) read this related post.
