{"id":4508,"date":"2013-04-08T12:02:55","date_gmt":"2013-04-08T09:02:55","guid":{"rendered":"http:\/\/railsware.com\/blog\/?p=4508"},"modified":"2025-02-14T15:23:04","modified_gmt":"2025-02-14T12:23:04","slug":"api-with-ruby-on-rails-useful-tricks","status":"publish","type":"post","link":"https:\/\/railsware.com\/blog\/api-with-ruby-on-rails-useful-tricks\/","title":{"rendered":"API with Ruby on Rails: useful tricks"},"content":{"rendered":"\n

This article is about gotchas you should be aware of while building your API with Ruby on Rails<\/a>.<\/p>\n\n\n\n

Controller tricks: API on Metal<\/h2>\n\n\n\n

Sooner or later each Rails developer<\/a> come to a point when he wants to build his first API.
Among the first things you have to take care of are your controllers.
If you want your API to be fast (and I bet you do) then you should consider using ActionController::Metal<\/a>.
The trick is that ActionController::Base<\/code> has many Middlewares that are not necessary for the API, by using Metal controller with minimum modules included, the one can achieve up to 40% speedup<\/a>.
Lets see what your basic metal controller may looks like:<\/p>\n\n\n\n

class Api::V1::BaseController < ActionController::Metal\n  include ActionController::Rendering        # enables rendering\n  include ActionController::MimeResponds     # enables serving different content types like :xml or :json\n  include AbstractController::Callbacks      # callbacks for your authentication logic\n\n  append_view_path \"#{Rails.root}\/app\/views\" # you have to specify your views location as well\nend<\/pre>\n\n\n\n
Unfortunately NewRelic doesn’t support Metal by default, so you have to add monitoring manually<\/a>.<\/p>\n\n\n\n
Routing: use versioning<\/h2>\n\n\n\n
Nobody’s perfect. So are we.
Your API will definitely be changed and extended multiple times in the future so you better take care of your versioning at the beginning.
As you noticed, BaseController<\/code> wrapped in V1<\/code> namespace. Use something like this in your routes:<\/p>\n\n\n\n
namespace :api do\n  namespace :v1 do\n    # put your routes here\n  end\nend<\/pre>\n\n\n\n
Views tricks: RABL ’em all<\/h2>\n\n\n\n
You don’t want to burden your code with logic of exposing different model fields for different API actions, right?
In this case you should use some template engine. RABL<\/a> is at your service. Here’s an example of your view:<\/p>\n\n\n\n
object @object\n\nattribute :public_id => :id\nattributes :title, :created_at, :source\n\nchild :contacts do\n  attributes :title\nend\n\nchild :files do\n  attributes :filename, :content_type, :size\nend<\/pre>\n\n\n\n
Also that will save you time by getting rid of ugly respond_to<\/code> blocks. Instead of<\/p>\n\n\n\n
def show\n  @object = Object.find(params[:id])\n  respond_to do |f|\n    f.json { render json: @object.to_json }\n    f.xml  { render xml: @object.to_xml }\n  end\nend<\/pre>\n\n\n\n
You can simple do literally Nothing<\/p>\n\n\n\n
def show\n  @object = Object.find(params[:id])\nend<\/pre>\n\n\n\n
Just make sure you have a RABL view in a corresponding directory.<\/p>\n\n\n\n
Security<\/h2>\n\n\n\n
There’re plenty of articles about API security best practices with OAuth and OIDC<\/a>. Another convenient way is to simply use token passed in the query string. If you ended up with token keep in mind that you can easily generate it by calling SecureRandom.urlsafe_base64<\/code>. To make sure token is unique you can use something like this:<\/p>\n\n\n\n
def build_token\n  begin\n    token = SecureRandom.urlsafe_base64\n  end while User.exists?(api_token: token)\n  token\nend<\/pre>\n\n\n\n
Hiding your IDs with GUIDs<\/h2>\n\n\n\n
By default Rails uses incremental integer for primary key.
Common practice is not to expose these kind of IDs to the public via your API because users can guess other IDs in your database and that might be a potential risk.
To solve this you can come up with a simple algorithm that will convert your IDs into some “safe” form and back.
But still it’s not super safe because someone can find out what the algorithm is.
Another possible solution is to expose GUIDs<\/a> to the public.
It’s a 128 entity that typically looks like this:<\/p>\n\n\n\n
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11<\/pre>\n\n\n\n
To generate it in Ruby use SecureRandom.uuid<\/code> (generates V4 GUID).
You can store it as a simple string column but if you are using Postgresql then you can utilize it’s built in uuid<\/code> type – this can save you a lot of space<\/a>.
Rails, however falls back to :string<\/code> for the uuid<\/code> Postgresql native type.
To workaround this you can create column manually in your migration (index should be added as well):<\/p>\n\n\n\n
execute \"ALTER TABLE objects add COLUMN public_id uuid NOT NULL DEFAULT uuid_generate_v4()\"\nadd_index :objects, [:public_id], name: \"index_objects_on_public_id\", unique: true<\/pre>\n\n\n\n
To use uuid_generate_v4<\/code> function you have to add Postgresql extension:<\/p>\n\n\n\n
create extension \"uuid-ossp\"<\/pre>\n\n\n\n
And don’t forget to change your schema format to :sql<\/code> in config\/application.rb<\/code><\/p>\n\n\n\n
config.active_record.schema_format = :sql<\/pre>\n\n\n\n
Testing your API<\/h2>\n\n\n\n
You definitely want to cover up your new shiny API with some sort of tests. See example below that uses Rack::Test::Methods<\/code><\/p>\n\n\n\n
# spec_helper\nmodule ApiHelper\n  include Rack::Test::Methods\n\n  def app\n    Rails.application\n  end\nend\n\nRSpec.configure do |config|\n  config.include ApiHelper, api: true\nend\n\n# spec\nrequire 'spec_helper'\n\ndescribe \"api\/v1\/objects\", api: true do\n  let(:url) { \"api\/v1\/objects\" }\n  let(:object) { Factory.create(:object) }\n  let(:token) { \"YOUR_SECRET_TOKEN\" }\n  let(:data) { JSON.parse(last_response.body) }\n\n  before(:each) { get url, token: token }       # here's where API call made\n\n  subject { data }\n\n  it { should have(1).object }\nend<\/pre>\n\n\n\n
Conclusion<\/h2>\n\n\n\n
We’ve just gone through the following tricks:<\/p>\n\n\n\n