Rails: Rest API post-mortem analysis

This is a personal post-mortem analysis of a project that was mainly build to provide a REST API to mobile clients.

For the API backend we used the following components:

  • Active Model Serializer (AMS) to serializer our Active Record models to JSON.
  • JSON Schema to test the responses of our server.
  • SwaggerUI to document the API.

It worked

The concept worked really good. Here are two points that were extraordinary compared to normal Rails project with many UI components:

  • Having a Rails application, that has no UI components (only…
Linked contentRepeats

Taking screenshots in Capybara

Capybara-screenshot can automatically save screenshots and the HTML for failed Capybara tests in Cucumber, RSpec or Minitest.

Requires Capybara-Webkit, Selenium or poltergeist for making screenshots. They're saved into $APPLICATION_ROOT/tmp/capybara

The attached files contain config for cucumber integration and a Then show me a screenshot step.

Linked contentRepeats

Showing a custom maintenance page while deploying

Add a custom maintenance page for each vhost (require capistrano 3.x):


Add this line to your application's Gemfile:

gem 'capistrano', '~> 3.0'
gem 'capistrano-maintenance', '~> 1.0'

Add this line to you application's Capfile:

require 'capistrano/maintenance'

Enable task

Present a maintenance page to visitors. Disables your application's web interface by writing a #{maintenance_basename}.html file to each web server. The servers must be configured to detect the presence of this file, and if it i…


Defining new elements for your HTML document

Browsers come with a set of built-in elements like <p> or <input>. When we need a new component not covered by that, we often build it from <div> and <span> tags. An alternative is to introduce a new element, like <my-element>.

When a browser encounters an unknown element like <my-element>, the browser will proceed to render <my-element>'s children. The visual rendering of your page will not be affected.

If you care about their HTML being valid, your new element should contain a dash character (-) to mark it as a *custom el…


FileIO: Writing strings as Carrierwave uploads

When you have string contents (e.g. a generated binary stream, or data from a remote source) that you want to store as a file using Carrierwave, here is a simple solution.

While you could write your string to a file and pass that file to Carrierwave, why even bother? You already have your string (or stream).
However, a plain StringIO object will not work for Carrierwave's ActiveRecord integration:

>> Attachment.create!(file:
TypeError: no implicit conversion of nil into String

This is because Carrierwave ex…

jQuery promises: done() and then() are not the same

jQuery's deferred objects behave somewhat like standard promises, but not really.

One of many subtle differences is that there are two ways to chain callbacks to an async functions.

The first one is done, which only exists in jQuery:

$.ajax('/foo').done(function(html) {
  console.debug("The server responded with %s", html);

There is also then, which all promise libraries have:

$.ajax('/foo').then(function(html) {
console.debug("The server resp…


Common mistakes when storing file uploads with Rails

1. Saving files to a directory that is not shared between deploys or servers

If you save your uploads to a made up directory like "RAILS_ROOT/uploads", this directory goes away after every deploy (since every release gets a new). Also this directory is not shared between multiple application servers, so your uploads are randomly saved to one local filesystem or another. Fixing this afterwards is a lot of fun.

Only two folders are, by default, shared between our application servers and deployments: "RAILS_ROOT/storage" and `"RAILS…

Linked contentRepeats

How to view a file from another branch

Just run git show branch:file. Examples:

git show HEAD~:bin/command
git show origin/master:../lib/version.rb

Fixing flaky integration tests

This card shows basic techniques for fixing a flaky integration test suite that sometimes passes and sometimes fails. "Integration test" is a test script that remote-controls a web browser with tools like Selenium WebDriver.

Although the examples in this card use Cucumber and Selenium, the techniques are applicable to all languages and testing tools.

Why tests are flaky

Your tests probably look like this:

When I click on A
When I click on B
When I click on C
Then I should see effects of C

A test like this works fine most of t…


XHR is not JSON

When a Rails controller action should handle both HTML and JSON responses, do not use request.xhr? to decide that. Use respond_to.

I've too often seen code like this:

def show
  # ...
  if request.xhr?
    render json: @user.as_json
     # renders default HTML view

This is just plain wrong. Web browsers often fetch JSON via XHR, but they (should) also send the correct Accept HTTP header to tell the server the data they expect to receive.

If you say request.xhr? as a means for "…

Linked content

Defining "partials" in pure HTML without additional rendering helpers

A while ago I tweeted a thread about how a small JavaScript snippet, one that can fit in a single tweet in fact, can be used to allow defining custom elements purely in HTML. This post will expand on the idea, show how the snippet works, and argue for why you might want to actually use this.

A nice trick that lets you define "partials" in HTML without any additional rendering technology on the server or client.


Pattern: Disabling a certain feature in tests

There is a kind of features in web applications that hinder automated integration tests. Examples include cookie consent banners or form captchas. Clearly, these should be disabled so you do not have to explicitly deal with them in each and every test (like, every test starting with accepting the cookies notice). On the other hand, they must be tested as well.

A good feature disabling solution should therefore meet these requirements:

  • The feature is generally disabled in tests. A test does not need to do anything manually.

  • It is *…

Linked content

Can I Email: Check what styling email clients support

The french Tilt Studio built a caniuse clone for email clients.

Note that while checking styling support helps using (or not using) certain features, it cannot substitute for checking the actual rendering in real clients. Make sure you follow Designing HTML Emails.


Be careful when using buttons without a "type" attribute

Be careful when using buttons without a type attribute, since browsers will consider them the default submit button of a form.

Suppose you have this form:

<form action="/save">
  <input type="text" />
  <button onclick="alert('Alert!')">Alert</button>
  <button type="submit">Save</button>

If you press the enter key inside in the text input, browsers will trigger the first button and show the alert.

To fix this, add a type="button" attribute to the first button.

Linked contentRepeats

ActiveSupport includes Timecop-like helpers

ActiveSupport (since 4.1) includes test helpers to manipulate time, just like the Timecop gem:

  • To travel a relative amount of time, use travel:

  • To travel to a specific moment in time, use travel_to:

    travel_to 1.hour.from_now
  • To freeze a specific time, use freeze_time (ActiveSupport 5.2+):

    freeze_time 1.hour.from_now

All those methods may also receive a block to call and restore time afterwards. If you don't provide a block, you must call `travel_bac…

Minified JavaScript and CSS

JavaScripts and CSS should be minified for production use.

In Rails 3.1+ the asset pipeline will take care of this. Thus you're best off using an uncompressed version of your Javascript in development. Also load the non-minified versions of libraries. This way debugging will be easier and you will still get all the minification love once deployed.

In Rails 2.3 and 3.0 you should at least embed external JavaScript libraries in minified form, using something like JavaScript compressor.


Be careful to use correct HTTP status codes for maintenance pages

When your public-facing application has a longer downtime for server maintenance or long migrations, it's nice to setup a maintenance page to inform your users.

When delivering the maintenance page, be very careful to send the correct HTTP status code. Sending the wrong status code might get you kicked out of Google, or undo years of SEO work.

Here are some ways to shoot yourself in the foot durign maintenance:

  • If all your routes send a "200 OK" with a HTML body "We're b…

Rails: Verify the CSRF token

Rails uses a CSRF token in forms and AJAX requests to verify a user request. Internally it compares the injected CSRF token of the form data with the CSRF token in the encrypted user session. To prevent SSL BREACH attacks, the CSRF token from the form data is masked.

To better debug issues, when these tokens do not match, it is useful to unmask the CSRF token from the form da…

This website uses cookies to improve usability and analyze traffic.
Accept or learn more