Why we chose JSON-RPC over REST

If you don’t want to mess about with XML, REST is pretty much the industry standard for creating an API.

Initially, we had a REST(ish) API. But after using it internally at HomeRez, we were not very happy with how it works. So we looked around for alternatives.

In the end, we decided to go for JSON-RPC.

What are the differences?

• REST uses HTTP  or HTTPS . JSON-RPC can use any transport protocol, for example TCP .
• JSON-RPC has 1 end-point URL for all requests. REST uses different URLs for different resources.
• In JSON-RPC, any request is sent the same way (e.g. via HTTP POST ) with the method and parameters in it. In REST, you use the HTTP verbs (GET , POST , PUT , DELETE ) for different actions.

So, what made us switch from REST to JSON-RPC?

The main reason is that we couldn’t find a good way to map all operations in our API to HTTP verbs. We have several operations that are not pure Create, Read, Update or Delete operations.

For example, we want a call to calculate the rent for staying at an apartment for a specific period. That isn’t really GET /apartment/rent  because we’re not retrieving a “rent” object that we can then PUT  to update. It also isn’t something like POST /apartment/calculate_rent , because that isn’t very RESTish.

Cancelling a reservation is another operation that gave us doubts. Calling PUT /reservation/<id>  with data { guestFirstName: “John” }  seems very different compared to calling it with data { status: “CANCELLED” } . The first simply updates a field, while the second has a lot of side effects: emails being sent to the guest and the owner, payments being refunded, the apartment becoming available again, etc. Maybe POST /reservation/<id>/cancel  would be ok, but that also doesn’t seem very RESTish – after all, you are modifying a reservation.

It became clear to us that we wanted to have an action-based API, where most of the calls perform actions. Many of those actions are different from from the traditional CRUD operations.

One other thing that bothered us, is GET  requests with lots of parameters. For example, let’s say you want to search reservations by a guest named “John Doe”. In JSON, the search parameters could look something like this:

{
    "guest": {
        "firstName": "John",
        "lastName": "Doe"
    }
}

However, if you put this information in the GET parameters, it becomes a bit tricky. You need to take escaping into account (where &  becomes &amp; ). If you just do the traditional ?a=1&b=2  parameters, you don’t have support for sub-structures. So you could turn your parameters into a JSON string, encode it, and then decode it on the server, but why make it so complex?

Yes, for a URL that you visit in your browser, it’s great that everything is in the address bar. It’s great that you can bookmark such a search. But we’re talking about an API here, not about a page being visited in the browser.

So, now we post all API calls to the same URL, with a method and a parameter object. Authentication fields are also sent in the parameter object, so we can easily switch our transport layer from HTTPS  to something else for better performance, if we want.

An additional advantage is that we can now easily use json-schema both to validate the incoming requests and to auto-generate most of our API documentation.

Examples of our calls are:

• reservation.create  to create a reservation
• reservation.quote  to get a quote (rent calculation) for a specific vacation home and period
• reservation.cancel  to cancel a reservation
• reservation.list  to get a list of reservations based on the search parameters
• property.list  to get a list of properties (vacation homes) based on the search parameters
• property.rate.list  to get all rates of a single vacation home

All in all, we are very happy with this switch.