Building APIs in Ruby: Rails 5 and Grape

Wondering what to build you next API in? Consider Ruby. With multiple robust open-source frameworks and a fantastic community behind it, Ruby is an excellent choice when getting started with larger API projects. Let’s take a look at two popular frameworks to see how you can use them to develop brilliant APIs.

Rails

Rails 5 is coming, and it has some exciting new changes, especially for those of us in the API space. The Rails-API gem has been integrated so that you can generate and scaffold your API without all of the unnecessary browser and HTML-related overhead that Rails usually carries with it. The resulting API-only application is faster and makes customizing data serialization (how you render your data in JSON or XML) a breeze.

Even though Rails 5 is not officially released yet, you can begin playing around with it by cloning the master branch from the git repository or specifying that repo as the Rails gem source in your project’s Gemfile. Then you can generate your API by running rails new <app_name> –edge –api. The api flag is important because this tells Rails to skip non-API steps, like cookie and session middleware.

Once you have your API, you can scaffold a resource (books, in this example) by running rails g scaffold books title description. You’ll see that this creates a model, database migration, controller, and serializer – the serializer is the view layer in our API MVC framework. Migrate the database with rake db:migrate to add the new books table with title, description, and timestamp columns to your database. Now when you start your server with rails s, you have a fully functioning web server with RESTful routes and endpoints for books.

If you’re a REST nut like I am, you can make your API fully RESTful with hypermedia with only one line of code. Make an active_model_serializer.rb file in your config/initializers directory, and add this line:

Now when you restart your server, you’ll see that your responses are returned in a JSON format that’s compliant with the JSON+API hypermedia spec. If you’re looking to integrate a different hypermedia format, check out the gem roar, which provides HAL support in JSON and XML.

Documentation with Swagger is easy with the help of the gem swagger-docs, which allows you to document your resource controllers and then generate your Swagger definition in JSON with a simple rake task run from the command line: rake swagger:docs. Then you can plug that definition into your Swagger UI to generate great documentation.

For a complete example and the steps to get started, see https://github.com/switzersc/rails-5-api-tutorial

Grape

If you’re looking to try a Ruby framework that is more lightweight than Rails but still has out-of-the-box API support, look no further than Grape. Getting started with Grape is as simple as installing the gem, creating an API class that inherits from Grape::API, and making a config.ru file that runs the rack webserver.

Swagger integration is even simpler than it is with Rails: with the grape-swaggergem, you can simple use the method add_swagger_documentation in your root API class to generate your Swagger definition. Hypermedia is also possible, although you may have to do a bit more legwork to integrate the roar gem or other serializers. Check out the grape-roar gem for more help in that arena.

To find a full example of a books API in Grape, seehttps://github.com/switzersc/grape-api-tutorial

Shelby Switzer is a Ruby API Engineer, speaker, and writer.

To watch an overview of creating APIs in Ruby, watch the webinar she helped host with SmartBear.