Integrating Native Mobile Applications and Rails

As stated above, HTML serves presentation, navigation, and state information to a browser in a generic way. HTML's ability to express of data is limited because it combines data with presentation constructs. Clients such as a mobile application are better served receiving data expressed in a data-centric protocol, such as JSON or XML. Other HTML-supplied state information, such as how to render the data, navigation links, and where to post data back to the server, is hard-coded into the mobile application's custom screens.

As a result, our Rails server must be able to render HTML to web browsers, and JSON to mobile applications. Rails makes vanilla JSON generation easy:

render :json => @work_orders 

Data within the Rails server is normalized (i.e. broken into objects that reference other objects). Objects are segregated along their natural atomic boundaries, rather than around a display architecture. When a page of HTML is to be rendered, the data is retrieved from the database with one or more (typically more) queries, and the results serialized.

Performance Considerations

In the above JSON rendering, however, we are rendering our literal representation of the object itself. In theory, it is the mobile application that knows what data is to be rendered on a screen, and that needs to retrieve the required data from the web server. However, in practice, successive round trips to the server need to be avoided, due to the additional latency inherent in mobile web access. This is especially important when showing a list of data, to avoid a web-service version of the N+1 selects problem [8].

Again, Rails assists us, by allowing us to easily customize our JSON responses:

render :json => @work_orders.to_json(
  :include => {
    :customer => {
      :only => [:id, :name]
    }
  }
)

In the above example, we customized our list of work orders, by including in the response the customer name and identifier for each work order. This prevents the mobile application from having to request customer information for each individual work order.

Mobile Testing

Thorough testing of Rails applications is common due to the great support for testing built-in to Rails, test stub generation, and positive peer pressure from the Rails community. We can leverage Rails testing support for our mobile application.

As described above, mobile applications use separate logic when rendering responses. It is a good practice to test the JSON generation path in functional tests. This can be accomplished by setting the accept header to "application/json" in the ActionController::TestRequest.

A small helper in test_helper.rb makes this easy to invoke:

class ActionController::TestRequest
  def json
    self.accept = "application/json"
  end
end 

In some cases, invoking JSON rendering and verifying a successful return status is sufficient for testing. In other cases, the contents of the JSON response should also be verified. The proper place to test response content is within Rails functional tests.

Rails allows us to parse JSON responses using the JSON.parse method.

test "work orders should include customer name" do
  @request.json
  get :index
  assert_response :ok
  work_orders = JSON.parse @response.body
  assert_equal(3, work_orders.size)
  work_orders.each do |wo|
    assert(wo["customer"])
    assert(!wo["customer"]["name"].blank?)
  end
end

In the above example, we verify a successful response, that 3 work orders are returned, and that a customer name is included for each work order.

Authentication

The mobile application is able to retrieve and display sensitive data, such as client lists. In order to assure only approved employees are able to use the service, an authentication system must be in place. This is common for HTML-based sites, where a user types in a login ID and a password. For a mobile application, where typing can be more difficult, this brings new challenges to both the sign up and log in processes.

The popular Authentication Gem Authlogic [9] worked well for our hybrid mobile application. We chose to eliminate the entry of a user ID, and use the mobile device's identifier for registration and log in, but is never shown to the user. Should mobile users need to access the site via a browser, they would use their email address to sign in.

Logged in mobile and browser users are tracked using Rails sessions, which are implemented using cookies. Mobile applications need not do anything special to preserve cookies — built-in HTTP client libraries allow them to persist from request to request.

State Management

Most applications are complex, involving many steps or interactions by the user to accomplish a task. In our workforce management application, mobile workers log in, clock in to their shift, view a custom list of work orders, retrieve details of a selected work order, arrive on site, start their job, provide details about the work performed, stop their job, and ultimately stop their shift and log out.

While these interactions are independent to the user, they are related to one another. Although they occur over a long time period, the server needs to know the details of the entire interaction in order to save it in our data model.

For example the server needs to model:

• which user started their shift;
• which user on what shift started which job;
• which job was stopped;
• which shift was stopped; and
• which user logged out.

We could require the mobile application to remember this state and reflect it back to the server. However, this would subject the mobile application to additional complexity, and subject our system to security problems.

We preserve the state on the server by:

• Keeping an HTTP session, through Rails cookie-based session capability, allowing the server to always know the logged in user's identity; and
• Modeling the user state, storing the user's shift and job status and recalling them on demand.

This allows the protocol to be simplified, freeing the mobile application from having to remember the logged-in user's user ID, shift ID, and job ID.

Error Handling

In addition to rendering custom JSON data responses, the Rails server frequently handles data posted back, with no expected response to render. In these cases, it either needs to render an HTTP OK status, or provide an error back to the mobile application.

An error may be a failure on the server, or a user error, such as a data validation error. In any case, the server should be able to easily:

• return an HTTP OK status when no errors occur;
• render a failure status along with a message suitable for display to the user; or
• render a hidden error details message suitable for writing to the server log and mobile debugging log.

The error itself may be an error condition coded in a controller, or one derived from our Active Record validations. We accomplished error handling using a lightweight error class, a helper function in our ApplicationController, and creating an error instance where needed, and invoking our helper function.

First, the helper function:

def render_error_or_ok
  if @error
    Rails.logger.error "ERROR: #{@error.system_message}"
    render :status => @error.status, :json => @error.to_json
  else
    head :ok
  end
end

If we are to either render an error or an ok status, using this helper allows us to do so in only one line. JSON is assumed, so this should be done within a JSON formatting block, or where there is no HTML access. Controllers only need to set @error if there is an error, prior to calling render_error_or_ok

The error class looks like this:

class AppError
  attr_accessor :status, :user_message, :system_message

  def initialize status, user_msg, system_msg = nil
    @status, @user_msg, @system_msg = status, user_msg, system_msg
  end

  def system_message
    @system_msg || @user_msg
  end

  def self.for_model m
    unless m.valid?
      errors = m.errors.full_messages.join(".\n")
      AppError.new(:bad_request, errors, 
                   "Validation errors: #{errors}")
    end
  end
end

The AppError class can be constructed given a status and error message(s), or using an Active Record object. Note that the second form returns nil if there is no error, so it can be safely assigned to @error even if the model is valid:

@error ||= AppError.for_model(@report) 

Explicit errors can also be created:

@error = AppError.new(:bad_request, "Access Denied", 
                      "User tried to access admin page")

Conclusion

Using Rails to develop the back-end server in a hybrid mobile application brings the productivity of Rails/HTML into the mobile arena. While the HTML rendering helpers are irrelevant when rendering JSON for mobile, the many other productivity features of Rails are equally important as when programming for browsers. Active Record remains an effective object-relational mapping, generators continue to speed development, and the rich list of Gems still deliver. In addition, allowing browser access makes the full power of Rails useful in this arena.

References

• [1] Android
  http://www.android.com
• [2] iPhone
  http://www.apple.com/iphone
• [3] Amazon.com mobile
  http://amazon.com/gp/aw/h.html
• [4] iHandySoft Level Free
  http://www.ihandysoft.com/level_free.html
• [5] Foursquare
  http://foursquare.com
• [6] Ruby on Rails
  http://www.rubyonrails.org
• [7] Model-View-Controller
  http://en.wikipedia.org/wiki/Model-View-Controller
• [8] N+1 Selects Problem
  http://www.realsolve.co.uk/site/tech/hib-tip-pitfall.php?name=why-lazy
• [9] Authlogic
  http://github.com/binarylogic/authlogic