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.
Answer
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:
- Clients are required to know procedure names;
- Procedure parameters order, types and count matters. It's not that easy to change procedure signatures(number of arguments, order of arguments, argument types etc...) on server side without breaking client implementations;
- RPC style doesn't expose anything but procedure endpoints + procedure arguments. It's impossible for client to determine what can be done next.
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:
- It's possible (and actually mandatory) to embed links annotated with link relation types which convey meanings of these URIs;
- Client implementations do not need to depend on particular procedure names and arguments. Instead, clients depend on message formats. This creates possibility to use already implemented libraries for particular media formats (e.g. Atom, HTML, Collection+JSON, HAL etc...)
- It's possible to easily change URIs without breaking clients as far as they only depend on registered (or domain specific) link relations;
- It's possible to embed form-like structures in representations, giving clients the possibility to expose these descriptions as UI capabilities if the end user is human;
- Support for caching is additional advantage;
- Standardised status codes;
There are many more differences and advantages on the REST side.