JSON-RPC or RESTFULL?

Question

Between developing an API using JSON-RPC or REST (RESTFULL), I would like to know in which cases there are advantages/disadvantages in using one or the other.

OBS:
This may be through knowledge/experience or reference sources.

Answer 1

One of the most common misconceptions is that any call that uses HTTP verbs such as GET, PUT, POST rather than using SOAP links to expose an end-point service is called "Restful". This blurring of the line between REST and XML-RPC (or JSON-RPC, etc.) has some very significant practical consequences.

Confusing POX web services as "REST", many web API implementations never fully exploit the Restful architecture.

REST vs RPC

REST is not a framework like WCF, a protocol like HTTP, a framework like JAX-RS, or a communication format like SOAP. REST is an architecture, a structured way of representing a software solution - specifically, by exposing the aspects of a solution to a set of remote customers-consumers. The core principle of REST is that these aspects of a solution can be modeled as resources that the customer can consume or interact with.

This resource-oriented thinking, and not the implementation details of how communication between client and server takes place, is what REST really is. This is the fundamental difference between real Restful Apis and RPC based on HTTP verbs.

Why is this important? The Restful approach allows us to model our domain objects as hierarchical Urls consistent with semantic and predictable (vaguely) mapping to CRUD. Since HTTP comes with standard error codes, MIME types and generally does most of the heavy lifting, it is interesting to benefit from the no need to maintain a stack of protocols developed by the user, and which is subject to frequent modification.

The fundamental problem with PRC is coupling. RPC customers become closely linked to the implementation service in various ways and it becomes very difficult to change service implementation without breaking customers.

Consider the following example of HTTP Apis that model restaurant orders.

• The RPC API thinks in terms of "verbs", exposing the functionality of the restaurant with function calls that accept parameters and calls these functions through the HTTP verb that seems more appropriate - a 'GET' for a query, and so on, but the verb name is purely incidental and has no real influence on the actual functionality, since you are calling a different URL each time. Return codes are coded manually, and are part of the service contract.
• The REST API, in turn, models the various entities in the problem domain as resources, and uses HTTP verbs to represent operations against these resources - POST to create, PUT to update, and GET to read, retrieve. Each of these verbs, invoked in the same URL (resource), provides a different functionality. Common HTTP return codes are used to transmit the status of requests.

Examples:

Add an order:

• PRC: http://MyRestaurant:8080/Orders/PlaceOrder (POST: <Order OrderNumber="asdf"><Appetizer><Appetizer><Entree>Tacos</Entree><! --Rest of the order--></Order>)
• REST: http://MyRestaurant:8080/Orders/Order?OrderNumber=asdf (POST: <Order><Appetizer><Appetizer><Entree>Tacos</Entree><! --Rest of the order--></Order>)

Retrieving a request:

• PRC: http://MyRestaurant:8080/Orders/GetOrder?OrderNumber=asdf (GET)

• REST: http://MyRestaurant:8080/Orders/Order?OrderNumber=asdf (GET)

Updating an order:

• PRC: http://MyRestaurant:8080/Orders/UpdateOrder (PUT: <Order OrderNumber="asdf"><Appetizer><Appetizer><Entree>Pineapple Tacos</Entree><! --Rest of the order--></Order>)

• REST: http://MyRestaurant:8080/Orders/Order?OrderNumber=asdf (PUT: <Order><Appetizer><Appetizer><Entree>Pineapple Tacos</Entree><! --Rest of the order--></Order>)

References:

• REST vs RPC - What is Restful
• Stackoverflow: REST vs JSON-RPC