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

Why JSON RPC:

In case of REST apis, we have to define a controller for each functionality/method we might need. As a result if we have 10 methods that we want accessible to a client, we have to write 10 controllers to interface the client's request to a particular method.

Another factor is, even though we have different controllers for each method/functionality, the client has to remember wether to use POST or GET. This complicates things further. On top of that to send data, one has to set the content type of the request if POST is used.

In case of JSON RPC, things are greatly simplified because most JSONRPC servers operate on POST HTTP methods and the content type is always application/json. This takes the load off of remembering to use proper HTTP method and content settings on client side.

One doesn't have to create separate controllers for different methods/functionalities the server wants to expose to a client.

Why REST:

You have separate URLs for different functionality the server wants to expose to client side. As a result, you can embed these urls.

Most of these points are debatable and completely depend upon the need of a person.

Answer 2

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

Answer 3

Wrong question: imposes a manichean that not exist!

You can use JSON-RPC with "less verb" (no method) and preserve the minimal standardization necessary for sendo id, parameters, error codes and warning messages. The JSON-RPC standard not say "you can't be REST", only say how to pack basic information.

"REST JSON-RPC" exists! is REST with "best practices", for minimal information packing, with simple and solid contracts.

---

Example

(from this answer and didactic context)

When dealing with REST, it generally helps to start by thinking in terms of resources. In this case, the resource is not just "bank account" but it is a transaction of that bank account... But JSON-RPC not obligates the "method" parameter, all are encoded by "path" of the endpoint.

• REST Deposit with POST /Bank/Account/John/Transaction with JSON request {"jsonrpc": "2.0", "id": 12, "params": {"currency":"USD","amount":10}}.
  The JSON response can be something as {"jsonrpc": "2.0", "result": "sucess", "id": 12}

• REST Withdraw with POST /Bank/Account/John/Transaction ... similar.

• ... GET /Bank/Account/John/Transaction/12345@13 ... This could return a JSON record of that exact transaction (e.g. your users generally want a record of debits and credits on their account). Something as {"jsonrpc": "2.0", "result": {"debits":[...],"credits":[...]}, "id": 13}. The convention about (REST) GET request can include encode of id by "@id", so not need to send any JSON, but still using JSON-RPC in the response pack.

Answer 4

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

Answer 5

I've been a big fan of REST in the past and it has many advantages over RPC on paper. You can present the client with different Content-Types, Caching, reuse of HTTP status codes, you can guide the client through the API and you can embed documentation in the API if it isn't mostly self-explaining anyway.

But my experience has been that in practice this doesn't hold up and instead you do a lot of unnecessary work to get everything right. Also the HTTP status codes often don't map to your domain logic exactly and using them in your context often feels a bit forced. But the worst thing about REST in my opinion is that you spend a lot of time to design your resources and the interactions they allow. And whenever you do some major additions to your API you hope you find a good solution to add the new functionality and you didn't design yourself into a corner already.

This often feels like a waste of time to me because most of the time I already have a perfectly fine and obvious idea about how to model an API as a set of remote procedure calls. And if I have gone through all this effort to model my problem inside the constraints of REST the next problem is how to call it from the client? Our programs are based on calling procedures so building a good RPC client library is easy, building a good REST client library not so much and in most cases you will just map back from your REST API on the server to a set of procedures in your client library.

Because of this, RPC feels a lot simpler and more natural to me today. What I really miss though is a consistent framework that makes it easy to write RPC services that are self-describing and interoperable. Therefore I created my own project to experiment with new ways to make RPC easier for myself and maybe somebody else finds it useful, too: https://github.com/aheck/reflectrpc

Answer 6

I use vdata for RPC protocol: http://vdata.dekuan.org/

1, PHP and JavaScript are both okay. 2, Cross-origin resource sharing(CORS) call is still okay.