michaeldehaan.net

A recent mailing list thread brought up on XMLRPC vs SOAP vs REST and so forth, and I noticed there were not a lot of articles on Google about this that really addressed some of the high points. I figured I might as well be on Google too, so here is my opinion.

This is based on not only a few apps like Cobbler and Func, but also past work where I’ve touched almost all of these first hand — I always seem to get stuck working on the backend server components wherever I go. This is by design — I like it there.

So here are the plusses and minuses to everything, and I’ll put a mark beside all the ones I’ve used before. Hopefully this will provide useful ammo if someone faces the “you must use SOAP” mandate somewhere and is looking for good options — or for people who are just looking for additional data before making a choice.

XMLRPC:
+ easy to route around firewalls
+ has very nice libraries available in a wide array of languages that make it feel just like a locally used library
+ widely used in for systems management type applications
+ simple libraries exist that do not require a “web app” stack to be a server for it
+ does provide a mechanism for signaling remote faults and raising them in the caller
+ while it is XML based the user doesn’t have to care about the XML, auto-serialization is an awesome thing to have.
+ specification has been around for a long while and has not needed to change, which means it got most things right
+ easy to proxy security behind Apache and let it take the heat
- serialization works for basic nested data structures of normal types, so your API must be written to use basic datastructures or otherwise serialize data in XML. (Basic datastructures are fine for most applications)
- does not have a bool type and typically cannot represent “None” (NULL) without special parameters as it is not in the spec — but this can be designed around easily. Should None be in an API? Probably not.
- is not deemed as “enterprisey” by some people as SOAP if you must deal with developers who like things to be called “enterprisey”
- not good for transport of large files because it ships things as XML.

REST:
+ easy to route around firewalls
+ useful for uploading files as it can be rather lightweight
+ very simple if you just want to shove simple things at something and get back an integer (like for uploaders)
+ you get it for free in some web application stacks and it is easy to pitch to “mash up” style web developers
+ easy to proxy security behind Apache and let it take the heat
- does not define any standard format for the way the data is being exchanged (could be JSON, YAML 1.0, YAML 2.0, arbitrary XML format, etc)
- does not define any convention about having remote faults sent back to the caller, integer codes are frequently used, but method of sending back data is not defined. Ideally this would be standardized.
- may require a lot of work on the client side caller of the library to make use of data (custom serialization and so forth)
- not pitchable as an enterprisey API in most cases, unless you are talking to web developers

SOAP:
+ easy to route around firewalls
+ widely used in for systems management type applications
+ supports complex objects if you absolutely need them and don’t mind writing a lot of code for it
+ has crazy things like envelopes
+ does provide remote faults and raises them in the caller
+ easy to proxy security behind Apache and let it take the heat
- has crazy things like envelopes
- pretty high signal to noise ratio in wire format, might be a slight performance concern
- caller will probably have to do work to process return data and format objects correctly
- typically only has good libraries for “enterprisey” languages, though there are some nice looking exceptions
- not everyone understands all of it
- lots of related and optional standards are confusing and sometimes not complete
- typically causes dynamic language hackers to run screaming when it is mentioned.
- in most cases, all you really needed was XMLRPC anyway
- .NET tools say they speak SOAP, but if you look at the underlying implementations, they are encoding data in a giant XML glob inside the stream, making it only really work for .NET apps. Embrace and extend here, so if you are picking SOAP for compatibility with .NET apps, they speak a different language that isn’t really in the spirit of the game.

CIM
+ Well supported by major players in the systems management space, allows you to do things with their software
+ Supported by a lot of storage and server related stuff
+ Definitely holds up as “enterprisey” if you need to play in that sandbox
- Way too complex for most developers to be efficient in it, or even be able to use it
- Not a lot of good dynamic language bindings, if any
- Hardly any implementations of it doing anything useful
- It’s hard to not code to a specific implementation and make things portable.
- Poor (free) documentation, especially in terms of examples. Good documentation seems to require payment of fees and being on commitees.
- open implementations leave some things to be desired (memory consumption)
- lots of related and optional standards are confusing and sometimes not complete
- not really adopted much in the open source space due to barriers of entry
- typically causes dynamic language hackers to run screaming when it is mentioned.

WMI
- This is microsoft stuff and is not happily cross platform

WS-Man and WSDM
- Other attempts to redo CIM
- Still painful
- Most of the same problems
- In many cases, even less adoption

RMI
+ Feels like a local API, much like XMLRPC
+ Can provide some fairly nice remote exception data
- Java specific means this causes lock in and limits your options
- Has horrible versioning problems between different versions of clients
- Skeleton files must be compiled in like CORBA, which is not very flexible
- Serious pain in the ass to multiplex sockets and secure them
- Subjective, but feels like it blows up a lot.
- While this is Java tech, it’s not “enterprisey” if you need that. Not anymore.
- Not firewall friendly (with exemptions, but they are pain)

CORBA
- Dinosaur tech. Very similiar to RMI.

Custom Socket Server implementations
- You will get the security part wrong.
- People will have a hard time talking to you.
- You will make extra work for yourself.
- It’s a bad idea.

Just send commands as INSERTS through the database
+ This might be ok for some batch job kind of things
- Not really an API, too much access to maintain
- Unsuitable for remote or untrusted/read-only usage.

Just FTP files around into an “orders” directory
- Even worse, don’t do this either. This does not an API make.

DBus
+ Great for local communication on the desktop on Linux
- Has a fair amount of dependencies
- Not something you (edit: typically) use remotely

Your Favorite Message bus (This post is not about message buses)
+ Nice if you want to address multiple things at a time and need complex routing options, especially if you are building it for a datacenter type setup where you control everything
+ May be very fast
+ Can be called “enterprisey” if you need that
- Can be a bit difficult to deploy and configure for your users in some cases
- Not all of them have a wide variety of language support and therefore may create lockin (thankfully AMQP does and does not have this problem!)
- Probably not right if you are writing multi-platform code

Conclusion? I like simple code that gets the job done while still covering all the bases I need to cover. I don’t need it to cover ALL of the bases, just some of them.

I like XMLRPC because there are very good client libraries, standardizes it’s serialization formats (and handles this all behind the scenes), does not show a language bias, and makes things trivial for the caller — it looks just like a local API. If your marketect demands, you can call it a full fledged web service with a straight face — it is one — for instance, the Python API’s provide a way to enumerate remote methods just like WSDL does (or close enough). There are some things it is not perfect at, but in the Linux space, it is omnipresent and very easy to use, and I like things that allow me to build infrastructure with the bare minimum of work and access it from multiple places without too much lock in. It is also a simple standard that you can read and instantly understand, it does not hide behind any hard to obtain knowledge that makes it seem superior.

Now, you don’t have to do just one API format — You could do something clever and expose things more than one way, too, but that’s extra work and I like to be minimalistic.
Other people may have their own preferences. That’s ok.

Google: have at.