Build API server with Rails, the convenience way

Rails 5 introduce API-only application. This provides lots of convenience. However this note will focus on API applications with Rails 4 and a simple CRUD backend.

  • Quick CRUD admin interface
  • API documentation
  • Authentication & Authorization
  • JSON serializeration
  • Cross-Origin Resource Sharing
  • Rate limit, blocking & throttling

Quick CRUD admin interface

Often a simple admin inteface that does CRUD functions with simple filter is a nice thing to have, some time a need. However it is really a pain to implement them: lots of repetitive code, although they are not hard but we still need time for it. Fortunately there are several gems out there that helps to sove this quickly.

Active Admin is the most popular one. It provides a quick admin interface in minutes. Though heavy customization is not easy, and default theme is somewhat not really beautiful and convenience, this gem is still handy for most cases.

Administrate is a newer gem, developed by Thoughtbot. It has simpler interface, fewer options and has modern look compared to Active Admin. A live demo of Administrate could be viewed here.

Because of the long delopment history and widely used, it is safe to go with Active Admin. You may also try Administrate if your requirements on backend is really simple.

API documentation

One API multiple clients is something very popular now. So an API server will serve multiple types of clients: web client that using AngularJS/React, iPhone/Android app, etc. So backend and frontend may be developed by different people. The most effective way for communication is API document.

Writing documents is the last thing most developer want to do, however it is a must to have a solid and clear API doc. Apipie is a gem for quick documentation with simple syntax and easy to use. A live example of Apipie doc could be seen here

Authentication

Devise auth token Token base authentication for Rails app, based on Devise gem.

Upon success login, server will return following properties:

"access-token": "wwwww",
"client":       "xxxxx",
"expiry":       "yyyyy",
"uid":          "zzzzz"

which will be used for authentication in subsequent requests. Those properties are included in request HTTP header.

Doorkeeper a gem that makes it easy to create OAuth service for Rails API app.

Sample login using email/password with Doorkeeper:

curl -F grant_type=password \
-F [email protected] \
-F password=doorkeeper \
-X POST http://localhost:3000/oauth/token

It will return someting like follow:

{"access_token":"0ddb922452c983a70566e30dce16e2017db335103e35d783874c448862a78168",
"token_type":"bearer",
"expires_in":7200,
"refresh_token":"f2188c4165d912524e04c6496d10f06803cc08ed50271a0b0a73061e3ac1c06c",
"scope":"public"}

access_token can be passed as url parameter in subsequent request or as header
with key - value as follow:

Authorization: Bearer 0ddb922452c983a70566e30dce16e2017db335103e35d783874c448862a78168

Authorization

Cancancan, a classic gem for authorization. Quickly to setup and use.

Pundit is a simple PORO with OO design. It is easy to use but take little more time to write code. In the long term project I prefer Pundit to Cancancan.

JSON serialization

Most APIs now use JSON as default data structure for sending and receiving data. There are many libraries in Ruby that helps with produce JSON effectively:

Jbuilder by default is bundled with Rails app. Its pros is that it is quick and easy to use. The down side is it mixes logic into view, considered as bad practice.

ActiveModelSerializers sticks closely with Rails models, provide quick helpers that allow extract JSON data quickly. One of the most popular libraries used for producing JSON.

Roar and Rabl are less popular but may be a good choice for your project.

One even can use PORO object to product JSON output.

Cross-Origin Resource Sharing

Sometimes frontend app has different domain from API server. Normally cross domain AJAX request is forbidden. Therefore we need to allow API server to receive and respond to cross domain AJAX request. rack cors gem will help quickly setting Cross-Origin Resource Sharing with several options.

Rate limit, blocking & throttling

Rack::Attack is a middleware for rate limit, blocking and throttling invalid requests.

Conclusion

A stack of Active Admin + Jbuilder/ActiveModelSerializers + Apipie + Devise Token Auth/Doorkeeper + Cancancan is a quick solution for simple API app.