Skip to main content

REST or JSON RPC

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 exampleTCP .
  • 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:
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
Incidentally, REST works very well with XML (as well as with JSON).
  1. For your examples, RESTful equivalents might be
    – POST /reservations to create a reservation
    – GET /reservations/quote?apartment=12&week=21 to get a quote
    – DELETE /reservations/123456 to cancel a reservation
    – GET /reservations?apartment=12 to get a list of reservations
    – GET /properties to get a list of properties
    – GET /properties/1234 to get all details (incl rates) of a single property
    or for rates if you didn’t want all details, you could create a new (sub-)resource
    – GET /properties/1234/rates to get rates of a single property
    If you check RESTful Web Services you will find there are many philosophical and practical benefits to a RESTful approach over an RPC interface

Comments

Popular posts from this blog

Sexy C#

Download samples   Table of Contents   1.   Introduction  2.   Background    3.   Sexy Features 3.1.   Extension Methods   3.2.   Anonymous Type   3.3.   Delegate   3.4.   Lambda Expression 3.5.   Async-Await Pair   3.6.   Generics   4.   Conclusion   1. Introduction     C#  is a very popular programming language. It is mostly popular in the .NET arena. The main reason behind that is the C# language contains so many useful features. It is actually a multi-paradigm programming language. Q.   Why do we call C# a muti-paradigm programming language? A.  Well, C# has the following characteristics:  Strongly typed   Object Oriented  Functional  Declarative Programming  Imperative Programming   Component based Programming Dynamic Programming ...

What Why How SDN..???????

What is SDN?   If you follow any number of news feeds or vendor accounts on Twitter, you've no doubt noticed the term "software-defined networking" or SDN popping up more and more lately. Depending on whom you believe, SDN is either the most important industry revolution since Ethernet or merely the latest marketing buzzword (the truth, of course, probably falls somewhere in between). Few people from either camp, however, take the time to explain what SDN actually means. This is chiefly because the term is so new and different parties have been stretching it to encompass varying definitions which serve their own agendas. The phrase "software-defined networking" only became popular over roughly the past eighteen months or so. So what the hell is it? Before we can appreciate the concept of SDN, we must first examine how current networks function. Each of the many processes of a router or switch can be assigned to one of three conceptual planes of operatio...

OpenDayLight Project --- SDN

OpenDaylight is a community-led, open, industry-supported framework, for accelerating adoption, fostering new innovation, reducing risk and creating a more transparent approach to Software-Defined Networking. OpenDaylight is a Collaborative Project at The Linux Foundation. It is structured using open source development best practices, and is comprised of the leading organizations in the technology industry. For more Information on OpenDayLight project, Please visit http://www.opendaylight.org/ for complete tutorial on OpenDayLight project, http://networkstatic.net/opendaylight-openflow-tutorial/