JSON-RPC or RESTFULL?

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

REST vs RPC

REST is not a framework such as WCF, a protocol such as HTTP, a framework like JAX-RS, or a communication format such as SOAP. REST is an architecture, a structured way to represent a software solution - specifically, exposing aspects of a solution to a set of remote client-clients. The central tenet of REST is that these aspects of a solution can be modeled as resources that the client can consume or interact with.

This resource-oriented thinking, not the implementation details of how client-server communication is, is what REST really is. This is the fundamental difference that separates actual RESTful RPC APIs based on HTTP verbs.

Why is this important? The RESTful approach allows us to model our domain objects as hierarchical URLs consistent with predictive (loosely) semantic mapping for CRUD. Because HTTP comes with standard error codes, MIME types, and usually does most of the heavy work, it is interesting to benefit from the need to maintain a stack of user-developed protocols, which is subject to frequent modification. / p>

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

Consider the following example of HTTP APIs that model the orders of a restaurant.

• The RPC API thinks in terms of "verbs," exposing restaurant functionality with function calls that accept parameters and calls these functions through the HTTP verb that seems most appropriate - a 'GET' for a query, and so on but the verb's 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 manually coded, and are part of the service agreement.
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 at the same URL (resource), provide different functionality. Common HTTP return codes are used to convey the status of requests.

Examples:

Add an order:

• RPC : 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 an order:

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

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

Updating an order:

• RPC : 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