REST vs JSON-RPC?

Question

I'm trying to chose between REST and JSON-RPC for developing an API for a web application. Which one is easier to use for API clients?

Update 2015: I have found REST easier to develop and use for an API which is served on Web/HTTP, because the existing and mature HTTP protocol which is understood by both client and server can be leveraged by the API. For example response codes, headers, queries, post bodies, caching and many other features can be used by the API without any additional effort or setup.

Answer 1

According to the Richardson maturity model, the question is not REST vs. RPC, but how much REST?

In this view, the compliance to REST standard can be classified in 4 levels.

• level 0: think in terms of actions and parameters. As the article explains, this is essentially equivalent to JSON-RPC (the article explains it for XML-RPC, but same arguments hold for both).
• level 1: think in terms of resources. Everything relevant to a resource belong to the same URL
• level 2: use HTTP verbs
• level 3: HATEOAS

According to the creator of REST standard, only level 3 services can be called RESTful. However, this is a metric of compliance, not quality. If you just want to call a remote function that does a calculation, it probably makes no sense to have relevant hypermedia links in the response, neither differentiation of behavior based on the HTTP verb used. So, a such call inherently tends to be more RPC-like. However, lower compliance level does not necessarily mean statefulness, or higher coupling. Probably, instead of thinking REST vs. RPC, you should use as much REST as possible, but no more. Do not twist your application just to fit with the RESTful compliance standards.

Answer 2

REST is tightly coupled with HTTP, so if you only expose your API over HTTP then REST is more appropriate for most (but not all) situations. However, if you need to expose your API over other transports like messaging or web sockets then REST is just not applicable.

Answer 3

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.

Answer 4

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