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.
I think there is one point people forgot to mention. If you already have a web app, then REST is desirable since you'll need the app server anyways and you can secure both using https... but if you do not have a web app, (just have an application), then RPC is desirable since you no longer need to setup an app server and configure it which is a hastle. Other than than, I don't see any real fundamental advantage in either.
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)
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.
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 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.