API Choice - JSON API V1 vs JSend

I am working on 2 Rails projects with APIs. Both applications use Grape mounted on Rails and swagger for documentation. The older TextbookValet.com API uses JSend based format for responses. The newer GivingFire.com API uses JSON API v1 compliant API. So what is the better option?

JSend

JSend dictates on the response format. It doss not provide any insight on how the API should behave or its format. One could argue its flexible. That is true. It allows you to architecture your API the way you desire.

Read more

JSON API v1

JSON API v1 on the other hand dictates just about every thing. It is a huge document to read. At best its boring and most new developers find it confusing. But its weakness is its strength. The convention mens any developer familiar with the specification will quickly adopt to the API. There is also the possibility of automation.

Read more

Why I choose JSend

If you would have followed my posts, you will know I dislike fragmentation. A sister project of TextbookValet.com was already using JSend. Mobile developers would use both my project (Rails website) and the Java application. Since the Java developer had already implemented it and the client preferred it, I decide to follow her footsteps.

What happened…

Here is what happened. I left the TextbookValet.com team about 6 months ago. I was asked to implement some minor updates. When I came back Java Spring developer asked me a question. Following convention, I gave an answer without looking in the code. I was wrong. Had it been built on a strict set of rules, every one would know what does what.

This is exactly why I love Rails. In a well built app, you know where to find what thanks to the Rails way of doing things.

Summary

While there is no restriction. Following a recognized format is important in the long term. Think about tomorrow and implement your new API using JSON API v1. You will save your self a lot of trouble.