I'm trying to chose between REST and JSON-RPC for developing an API for a web application. How do they compare?
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.
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:
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:
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:
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:
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:
Hope it helps mate!
Nacho
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.
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.
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
If your service works fine with only models and the GET/POST/PUT/DELETE pattern, use pure REST.
I agree that HTTP is originally designed for stateless applications.
But for modern, more complex (!) real-time (web) applications where you will want to use Websockets (which often imply statefulness), why not use both? JSON-RPC over Websockets is very light so you have the following benefits:
As you are only designing the server side API, start with defining REST models and later add JSON-RPC support as needed, keeping the number of RPC calls to a minimum.
(and sorry for parentheses overuse)
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.
I think, as always, it depends ...
REST has the huge advantage of widespread public support and this means lots of tools and books. If you need to make an API that is used by a large number of consumers from different organisations then it is the way to go for only one reason: it is popular. As a protocol it is of course a total failure since there are too many completely different ways to map a command to a URL/verb/response.
Therefore, when you write a single page web app that needs to talk to a backend then I think REST is way too complex. In this situation you do not have to worry about long term compatibility since the app and API can evolved together.
I once started with REST for a single page web app but the fine grained commands between the web app and the server quickly drove me crazy. Should I encode it as a path parameter? In the body? A query parameter? A header? After the URL/Verb/Response design I then had to code this mess in Javascript, the decoder in Java and then call the actual method. Although there are lots of tools for it, it is really tricky to not get any HTTP semantics in your domain code, which is really bad practice. (Cohesion)
Try making a Swagger/OpenAPI file for a medium complex site and compare that to a single Java interface that describes the remote procedures in that file. The complexity increase is staggering.
I therefore switched from REST to JSON-RPC for the single page webapp. aI developed a tiny library that encoded a Java interface on the server and shipped it to the browser. In the browser this created a proxy for the application code that returned a promise for each function.
Again, REST has its place just because it is famous and therefore well supported. It is also important to recognise the underlying stateless resources philosophy and the hierarchical model. However, these principles can just as easy be used in an RPC model. JSON RPC works over HTTP so it has the same advantages of REST in this area. The difference is that when you inevitably run into these functions that do not map well to these principles you're not forced to do a lot of unnecessary work.
It would be better to choose JSON-RPC between REST and JSON-RPC to develop an API for a web application that is easier to understand. JSON-RPC is preferred because its mapping to method calls and communications can be easily understood.
Choosing the most suitable approach depends on the constraints or principal objective. For example, as far as performance is a major trait, it is advisable to go for JSON-RPC (for example, High Performance Computing). However, if the principal objective is to be agnostic in order to offer a generic interface to be inferred by others, it is advisable to go for REST. If you both goals are needed to be achieved, it is advisable to include both protocols.
The fact which actually splits REST from JSON-RPC is that it trails a series of carefully thought out constraints- confirming architectural flexibility. The constraints take in ensuring that the client as well as server are able to grow independently of each other (changes can be made without messing up with the application of client), the calls are stateless (the state is regarded as hypermedia), a uniform interface is offered for interactions, the API is advanced on a layered system (Hall, 2010). JSON-RPC is rapid and easy to consume, however as mentioned resources as well as parameters are tightly coupled and it is likely to depend on verbs (api/addUser, api/deleteUser) using GET/ POST whereas REST delivers loosely coupled resources (api/users) in a HTTP. REST API depends up on several HTTP methods such as GET, PUT, POST, DELETE, PATCH. REST is slightly tougher for inexperienced developers to implement.
JSON (denoted as JavaScript Object Notation) being a lightweight data-interchange format, is easy for humans to read as well as write. It is hassle free for machines to parse and generate. JSON is a text format which is entirely language independent but practices conventions that are acquainted to programmers of the family of languages, consisting of C#, C, C++, Java, Perl, JavaScript, Python, and numerous others. Such properties make JSON a perfect data-interchange language and a better choice to opt for.
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.
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.
(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.
If you request resources, then RESTful API is better by design. If you request some complicated data with a lot of parameters and complicated methods other than simple CRUD, then RPC is the right way to go.
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.
