REST vs JSON-RPC? [closed]

Question

The fundamental problem with RPC is coupling. RPC clients become tightly coupled to service implementation in several ways and it becomes very hard to change service implementation without breaking clients:

• Clients are required to know procedure names;
• Procedure parameters order, types and count matters. It's not that easy to change procedure signatures(number of arguments, order of arguments, argument types etc...) on server side without breaking client implementations;
• RPC style doesn't expose anything but procedure endpoints + procedure arguments. It's impossible for client to determine what can be done next.

On the other hand in REST style it's very easy to guide clients by including control information in representations(HTTP headers + representation). For example:

• It's possible (and actually mandatory) to embed links annotated with link relation types which convey meanings of these URIs;
• Client implementations do not need to depend on particular procedure names and arguments. Instead, clients depend on message formats. This creates possibility to use already implemented libraries for particular media formats (e.g. Atom, HTML, Collection+JSON, HAL etc...)
• It's possible to easily change URIs without breaking clients as far as they only depend on registered (or domain specific) link relations;
• It's possible to embed form-like structures in representations, giving clients the possibility to expose these descriptions as UI capabilities if the end user is human;
• Support for caching is additional advantage;
• Standardised status codes;

There are many more differences and advantages on the REST side.

I have explored the issue in some detail and decided that pure REST is way too limiting, and RPC is best, even though most of my apps are CRUD apps. If you stick to REST, you eventually are going to be scratching your head wondering how you can easily add another needed method to your API for some special purpose. In many cases, the only way to do that with REST is to create another controller for it, which may unduly complicate your program.

If you decide on RPC, the only difference is that you are explicitly specifying the verb as part of the URI, which is clear, consistent, less buggy, and really no trouble. Especially if you create an app that goes way beyond simple CRUD, RPC is the only way to go. I have another issue with RESTful purists: HTTP POST, GET, PUT, DELETE have definite meanings in HTTP which have been subverted by REST into meaning other things, simply because they fit most of the time - but not all of the time.

In programming, I have long ago found that trying to use one thing to mean two things is going to come around sometime and bite you. I like to have the ability to use POST for just about every action, because it provides the freedom to send and receive data as your method needs to do. You can't fit the whole world into CRUD.

First, HTTP-REST is a "representational state transfer" architecture. This implies a lot of interesting things:

• Your API will be stateless and therefore much easier to design (it's really easy to forget a transition in a complex automaton), and to integrate with independent software parts.
• You will be lead to design read methods as safe ones, which will be easy to cache, and to integrate.
• You will be lead to design write methods as idempotent ones, which will deal much better with timeouts.

Second, HTTP-REST is fully compliant with HTTP (see "safe" and "idempotent" in the previous part), therefore you will be able to reuse HTTP libraries (existing for every existing language) and HTTP reverse proxies, which will give you the ability to implement advanced features (cache, authentication, compression, redirection, rewriting, logging, etc.) with zero line of code.

Last but not least, using HTTP as an RPC protocol is a huge error according to the designer of HTTP 1.1 (and inventor of REST): http://www.ics.uci.edu/~fielding/pubs/dissertation/evaluation.htm#sec_6_5_2

Great answers - just wanted to clarify on a some of the comments. JSON-RPC is quick and easy to consume, but as mentioned resources and parameters are tightly coupled and it tends to rely on verbs (api/deleteUser, api/addUser) using GET/ POST where-as REST provides loosely coupled resources (api/users) that in a HTTP REST API relies on several HTTP methods (GET, POST, PUT, PATCH, DELETE). REST is slightly harder for inexperienced developers to implement, but the style has become fairly common place now and it provides much more flexibility in the long-run (giving your API a longer life).

Along with not having tightly coupled resources, REST also allows you to avoid being committed to a single content-type- this means if your client needs to receive the data in XML, or JSON, or even YAML - if built into your system you could return any of those using the content-type/ accept headers.

This lets you keep your API flexible enough to support new content types OR client requirements.

But what truly separates REST from JSON-RPC is that it follows a series of carefully thought out constraints- ensuring architectural flexibility. These constraints include ensuring that the client and server are able to evolve independently of each other (you can make changes without messing up your client's application), the calls are stateless (state is represented through hypermedia), a uniform interface is provided for interactions, the API is developed on a layered system, and the response is cacheable by the client. There's also an optional constraint for providing code on demand.

However, with all of this said - MOST APIs are not RESTful (according to Fielding) as they do not incorporate hypermedia (embedded hypertext links in the response that help navigate the API). Most APIs you will find out there are REST-like in that they follow most of the concepts of REST, but ignore this constraint. However, more and more APIs are implementing this and it is becoming more of a main-stream practice.

This also gives you some flexibility as hypermedia driven APIs (such as Stormpath) direct the client to the URIs (meaning if something changes, in certain cases you can modify the URI without negative impact), where-as with RPC URIs are required to be static. With RPC, you will also need to extensively document these different URIs and explain how they work in relation to each other.

In general, I would say REST is the way to go if you want to build an extensible, flexible API that will be long-lived. For that reason, I would say it's the route to go 99% of the time.

Good luck, Mike

IMO, the key point is the action vs resource orientation. REST is resource-oriented and fits well for CRUD operations and given its known semantics provides some predictability to a first user, but when implemented from methods or procedures forces you to provide an artificial translation to the resource centered world. On the other hand RPC suits perfectly to action-oriented APIs, where you expose services, not CRUD-able resource sets.

No doubt REST is more popular, this definitely adds some points if you want to expose the API to a third party.

If not (for example in case of creating an AJAX front-end in a SPA), my choice is RPC. In particular JSON-RPC, combined with JSON Schema as description language, and transported over HTTP or Websockets depending on the use case.

JSON-RPC is a simple and elegant specification that defines request and response JSON payloads to be used in synchronous or asynchronous RPC.

JSON Schema is draft specification defining a JSON based format aimed at describing JSON data. By describing your service input and output messages using JSON Schema you can have an arbitrary complexity in the message structure without compromising usability, and service integration can be automatized.

The choice of transport protocol (HTTP vs websockets) depends on different factors, being the most important whether you need HTTP features (caching, revalidation, safety, idempotence, content-type, multipart, ...) or whether you application needs to interchange messages at high frecuencies.

Until now it is very much my personal opinion on the issue, but now something that can be really helpful for those Java developers reading these lines, the framework I have been working on during the last year, born from the same question you are wondering now:

http://rpc.brutusin.org

You can see a live demo here, showing the built-in repository browser for functional testing (thanks JSON Schema) and a series of example services:

http://demo.rpc.brutusin.org

Hope it helps mate!

Nacho