What are the benefits of switching legacy RPC style services over to REST?

Question

I am maintaining a legacy app full of RPC style* web services. For example, we have the following services for creating and deleting users from the system:

• https://example.com/createUser
• https://example.com/deleteUser

Clients call these services by submitting XML data over an HTTP POST. The XML request contains all the information necessary for the server to process the request (i.e. authentication information, user information). The server then responds with an XML document containing any information the client should be aware of (e.g. success/failure flags and descriptions).

I am interested in what the benefits are in switching these RPC style services to a more RESTful architecture. From what I've read, that would mean the following:

1. To create users, clients would still be required to submit XML data over HTTP POST (or PUT depending on whether they know the final URL and if they know all the necessary information for a user resource). However, authentication information would be passed in the HTTP headers using basic authentication.
2. To delete users, clients would issue an HTTP DELETE call to https://example.com/users/{user id}. Again, authentication information would be passed in the HTTP headers rather than in the request body. In fact, no request body should be necessary as far as I can tell.
3. Rather than indicating success / failure information in an XML document, the server should try to indicate as much as possible via the HTTP status code / status description.

Now as far as I can tell, the main benefits of changing these services to a more RESTful architecture are:

1. We'd be leveraging more of what HTTP has to offer, specifically in regards to authentication.
2. The URLs are a bit more logical, especially if we need to start exposing resources beneath the "user" level (e.g. https://example.com/users/{user id}/stuff).
3. It's more inline with the native architecture of the Web.

Am I missing anything? I feel like there should be more benefits to going with a RESTful architecture.

*Note that when I say "RPC style" I am not referring to a standardized format like XML-RPC or SOAP.

Answer 1

Without knowing anything about your application, from a practical and pragmatic perspective, converting to REST wouldn't gain you much of anything, especially in consideration of the potential development effort.

Do you have a large client base? Do you have lots of servers?

A key attribute (but not the only, nor even required, but...) of REST is how it leverages HTTP Caching.

Are you doing any caching? Is that a big deal for you? It is for large systems on the public internet.

If you're not using caching, and you don't think it would benefit you much (i.e. you don't have a lot of clients, your servers aren't super saturated, your content simply doesn't fit well, etc.), then REST is likely not even worth pursuing, as the other benefits are a lot less tangible than caching.

If you're just POSTing POX (Plain Ol XML) (or JSON) over HTTP, and that's working well for you, then I wouldn't worry about it.

There's other benefits to HTTP, naturally, with its media types, content negotiation, caching and location headers, etc. But, seriously, if you don't see doing much of that with your API, don't bother.

If the caching WOULD help you, then its worth leaping to a more full embrace of the HTTP protocol and stack, but no reason to go to a REST architecture for that. Cached POX over HTTP isn't REST either. Its...POX over HTTP.

That's all SOAP and XML-RPC are...POX over HTTP, just the SOAP XML brings along with it several very thick standards...

If you're a huge service organization, with a 10 year plan, then you might want to look at migrating to a full boat REST architecture as that's it's real place in the world -- long term, large systems.

But that's a real re-engineering effort to go that way.

Addenda:

One of the issues that REST tries to address is the coupling of systems.

RPC systems tend to be pretty strongly coupled.

So, as systems grow, that coupling becomes a drag on the evolution of the system.

Consider the two extremes of MS Windows and Linux. Microsoft spends a lot of time on trying to make MS Windows backward compatible to work with legacy (and even buggy) software. That costs them time and money.

In contrast, the Linux kernel is much more cavalier. When it comes to the kernel they make no promises on backward compatibility. Linux is (in)famous for it breaking drivers and what not from release to release. Their major saving grace is that they didn't promise anything in the first place, so don't be upset when something breaks.

This allows the Linux kernel folks to be more creative, and move faster because they can always toss and change things as they move along. It also lets the team be smaller.

Now consider a small RPC system of services. Since they're implicitly tightly bound (as is the nature with RPC), when the central service changes, that change is going to ripple out to all of the clients.

If those clients are few, and especially if they're in your control (as you develop the entire system rather than a component), the magnitude of the change isn't necessarily painful and disruptive.

But you can see that if you had thousands of clients, and/or clients you do not control implementing to spec, making changes to core services can have dramatic ramifications. Heck, I've sent people source code and they still get it wrong.

REST helps decouple systems by leveraging standard media types (i.e. not some XML you threw on the whiteboard one day), the HTTP Protocol (you don't need HTTP to have REST arch, but that's pretty much a given today), and HATEOS.

HATEOS is, roughly, where the client makes no assumptions about where things go. The client instead parses the results for links to the next steps in the process it's performing.

The classic example is you (the client) shopping Amazon. All you know is to click the "checkout" button, but you don't know what URL to go to. That URL can be fixed in stone, it can change every second, it can even lead to something that redirects you. YOU don't know, nor care. It's the servers prerogative.

So, as a client you know how to "click checkout" (i.e. follow the link in the most recent payload labeled 'checkout'), but you don't really know much more beyond that. Notably, you don't have "http://amazon.com/checkout" hard coded in your application.

Without going in to great detail how using these concept reduces coupling, at this stage simply accept that they do, and by reducing coupling you as a service provider have an easier mechanism for expanding, adding, and changing services while as a service consumer, you can focus your system on the aspects of the service that you are particularly interested in even if some underlying details change behind your back. Again, consider how much Amazon has changed over the years, but at least we all know where the Checkout button is.

But writing services like this, and creating clients like this, is really quite a bit of work. Some of the mechanics are "easy" because "we do it all the time" (serving up HTML responses for example, who doesn't do that?). But the larger scope of working with media types, facilitating change and evolution, and making your services and clients robust and friendly to this environment. That all takes work, for benefits not immediately realized.

"Why are we doing all this for a service that will never change?"

"Because never comes sooner than you think."

Web apps (like Amazon) succeed in a RESTy way because their clients happen to be human beings, which turn out to (mostly) be quite adaptable. But if you've ever moved the button of some core function on a popular website, your inbox lets you know how adaptable some people really are. Doing this at the machine level is even more difficult.

Mind, this is in stark contrast to the "don't build it if you don't need it" agile "we can just add it later" mindset.

That's why REST is better suited for larger systems with long term outlooks. It's much more strategic than tactical. Its more than just pushing bits over a socket to get a result.

Hope that helps.