JSON API v1 with Rails 3 - Libraries

This is the Part 2 of my experience on implementing an API on a Rails 3 app on JSON API v1 specifications. Part 1 is recommended to be skipped as it is ‘boring’.

Rails has a lot of resources when it comes to implement an API in compliance with JSON API v1 specifications. But unfortunately that requires Rails 4+. I had to settle with JSON API Serializers gem (which supports Sinatra and other Ruby frameworks too) and manually dealing with the rest.

For API documentation, I decided to settle with Swagger. I believe it doesn’t require justification.

Finally I ended up using the following…

Let me elaborate.

Grape v0.7

Grape is framework / DSL for building APIs. It doesn’t require Rails. Initially we were going to make the API standalone but later decided to mount it on the existing Rails application.

As I remember bundler choose grape v0.7. I tried to use a later version of Grape and ended up updating multiple gems version. Finally I had to update the Ruby version to 2.2 and Rails had to be updated to 3.2.22. Unfortunately the app was not functional at that point.

You may have better fortune and be able to install a better version of grape depending on your actual dependencies and if you can update to Rails 3.2.22.

Grape Swagger v0.8

In case you don’t know, grape-swagger is the lib that generates the definitions the swagger-ui require to display. This gem will introduce some helper methods that you can describe the API neatly.

This is not the newest grape-swagger version, it is many years old, but it will do. There is a compatibility chart in the master branch of the grape-swagger gem but it doesn’t cover old versions like grape v0.7.

I went through many versions to find a match. This version will give us Swagger 1.2 compatible JSON definitions.

Grape Entity v0.4.8

The idea of grape entity is to model requests and responses. For example we may have a User model but we may only want to expose fields like first_name, last_name and email. This does just that. With grape-wagger we are able to define the data types as well so it gets documented.

Documentation is the whole reason why you will need to get grape-entity involved. But I later found out that it is not ideal, but that is all we have.

Grape Swagger Rails v0.3

Grape Swagger Rails is a rails mounted Swagger UI. If you are not using Rails you don’t need to use this. Instead you can simply host the configured static Swagger UI separately.

This is no compromise. This is the latest version and supports swagger 1.2 compatible definitions.

Thats the libraries I have used and why I have used them.

this article is wip