The Ocean gem

This repository contains the Ocean ruby gem, containing common framework functionality for the Ruby on Rails part of the architecture.

Ocean requires Ruby 2.0 and Ruby on Rails 4.0.0 or later.


Creating an Ocean Rails app

The ocean gem provides an application template and generator to quickly and easily set up a complete Rails application for Ocean. Simply execute the following in your terminal:

rails new the_app_name -m

Answer yes to all overwrite queries.

There is only one piece of manual setup to perform. You must supply the Ocean app with your site-specific data: the base domain name, the password for Auth, etc. To do this, simply edit config/config.yml.

There is also a file called config.yml.example in the same directory for reference. Don't change it: it is under version control. The file you should change, config/config.yml, isn't, as it will contain site-specific and/or confidential data.

Verify that your setup is OK by executing


All tests should pass.

Creating an Ocean Resource

To create an aggressively cached Ocean resource based on an SQL model, do the following:

rails g scaffold quux name:string description:string \ 
                      lock_version:integer created_by:string updated_by:string

This will create the basic model and associated model and controller scaffolding code, which we will modify shortly. Now run

rake db:migrate

This will create the SQL table for the resource. Next, we need to replace the HTML-centric scaffold code generated above with RESTful JSON scaffold code for Ocean:

rails g ocean_scaffold quux

Answer yes to all overwrite queries. Now examine config/routes.rb. You will find a new resource declaration for quuxes. Move it inside the versioned scope and add and except: clause to exclude the Rails controller actions not used in a REST Api:

scope "v1" do
  resource :quuxes, except: [:new, :edit]

To verify that everything works as it should, run the tests:


All tests should pass. The test coverage should be very close to 100%. A FactoryGirl factory for the new model will be created, there will be model unit tests to check for the presence of all attributes and to verify collection searches, routing tests, controller tests for each action, and view tests to verify that the JSON representation is complete and correct.

You can now proceed to tailor the new resource to your needs. You will want to add other attributes to the model or remove some or all of the default ones; you can change the JSON representation by modifying the view; and you might want to add or remove controller actions, e.g. to support secondary collections and relations to other resources. And as you no doubt are a responsible, informed developer, you will of course do all this using TDD and/or BDD techniques.