If you’re looking for new ways to build maintainable, secure, faster and testable Ruby applications, you’re in for a treat. Hanami is built for people like you.

Whether you’re a total beginner or an experienced developer, this learning process may still be hard. Over time, we become used to certain things, and it can be painful to change. But without change, there is no challenge and without challenge, there is no growth.

In this guide we’ll set up our first Hanami project and build a simple web app. We’ll touch on all the major components of the Hanami framework, guided by tests at each stage.

If you feel alone or frustrated, don’t give up, jump into our and ask for help. We and the rest of our community are putting in our best efforts to make Hanami better every day.

Enjoy,
Luca, Peter and Tim
Hanami core team

Hanami is a Ruby framework designed to create software that is well-architected, maintainable and a pleasure to work on.

These guides aim to introduce you to the Hanami framework and demonstrate how its components fit together to produce a coherent application.

Ideally, you already have some familiarity with web applications and the .

Creating a Hanami application

To create a Hanami application, you will need Ruby 3.0 or greater. Check your ruby version:

If you need to install or upgrade Ruby, follow the instructions on ruby-lang.org.

In order to create a Hanami application, first install the hanami gem:

Hanami provides a hanami new command for generating a new application.

Let’s use it to create a new application for managing books called bookshelf:

  1. hanami new bookshelf

Running this command has created a new bookshelf directory in our current location. Here’s what it contains:

  1. cd bookshelf
  2. tree .
  3. .
  4. ├── Gemfile
  5. ├── Gemfile.lock
  6. ├── Guardfile
  7. ├── README.md
  8. ├── Rakefile
  9. ├── app
  10. │   ├── action.rb
  11. │   └── actions
  12. ├── config
  13. │   ├── app.rb
  14. │   ├── puma.rb
  15. │   ├── routes.rb
  16. │   └── settings.rb
  17. ├── config.ru
  18. ├── lib
  19. │   ├── bookshelf
  20. │   │   └── types.rb
  21. │   └── tasks
  22. └── spec
  23.     ├── requests
  24.     │   └── root_spec.rb
  25.     ├── spec_helper.rb
  26.     └── support
  27.         ├── requests.rb
  28.         └── rspec.rb
  30. 9 directories, 16 files

As you can see, a new Hanami application has just 16 files in total.

Here’s how these files and directories are used:

We’ll see this structure in more detail as this guide progresses.

For now let’s get our new application running. In the bookshelf directory, run:

  1. hanami server

If all has gone well, you should see output similar to:

  1. Puma starting in cluster mode...
  2. * Puma version: 6.0.0 (ruby 3.1.0-p0) ("Sunflower")
  3. *  Min threads: 5
  4. *  Max threads: 5
  5. *  Environment: development
  6. *   Master PID: 69708
  7. *      Workers: 2
  8. *     Restarts: (✔) hot (✖) phased
  9. * Preloading application
  10. * Listening on http://0.0.0.0:2300
  11. Use Ctrl-C to stop
  12. * Starting control server on http://127.0.0.1:9293
  13. * Starting control server on http://[::1]:9293
  14. - Worker 0 (PID: 69721) booted in 0.0s, phase: 0
  15. - Worker 1 (PID: 69722) booted in 0.0s, phase: 0

Visit your application in the browser at 

  1. open http://localhost:2300

You should see “Hello from Hanami”.

Adding our first functionality

Let’s take a look at Hanami by creating the beginnings of a bookshelf application.

In the file spec/requests/root_spec.rb, Hanami provides a request spec for the “Hello from Hanami” message we’ve seen in the browser.

  1. # spec/requests/root_spec.rb
  3. RSpec.describe "Root", type: :request do
  4.   it "is successful" do
  5.     get "/"
  7.     # Find me in `config/routes.rb`
  8.     expect(last_response).to be_successful
  9.     expect(last_response.body).to eq("Hello from Hanami")
  10.   end
  11. end

We can run that spec now to prove that it works:

  1. bundle exec rspec spec/requests/root_spec.rb

You should see:

  1. Root
  2.   is successful
  4. Finished in 0.01986 seconds (files took 0.70103 seconds to load)
  5. 1 example, 0 failures

Let’s change the “Hello from Hanami” message to “Welcome to Bookshelf”. First, we’ll adjust our spec:

  1. # spec/requests/root_spec.rb
  3. RSpec.describe "Root", type: :request do
  4.   it "is successful" do
  5.     get "/"
  7.     # Find me in `config/routes.rb`
  8.     expect(last_response).to be_successful
  9.     expect(last_response.body).to eq("Welcome to Bookshelf")
  10.   end
  11. end

As we expect, when we run the spec again, it fails:

  1. Root
  2.   is successful (FAILED - 1)
  4. Failures:
  6.   1) Root is successful
  7.      Failure/Error: expect(last_response.body).to eq("Welcome to Bookshelf")
  9.        expected: "Welcome to Bookshelf"
  10.             got: "Hello from Hanami"
  12.        (compared using ==)
  13.      # ./spec/requests/root_spec.rb:9:in `block (2 levels) in <top (required)>'
  15. Finished in 0.04572 seconds (files took 0.72148 seconds to load)
  16. 1 example, 1 failure

To fix this, let’s open our application’s routes file at config/routes.rb:

  1. # config/routes.rb
  3. module Bookshelf
  4.   class Routes < Hanami::Routes
  5.     root { "Hello from Hanami" }
  6.   end
  7. end

This Bookshelf::Routes class contains the configuration for our application’s router. Routes in Hanami are comprised of a HTTP method, a path, and an endpoint to be invoked, which is usually a Hanami action. (See the for more information).

We’ll take a look at adding more routes in a moment, but for now let’s get our spec to pass. The above Bookshelf::Routes class contains only one route, the root route, which handles GET requests for "/".

Rather than invoking an action, this route is configured to invoke a block, which returns “Hello from Hanami”.

Blocks are convenient, but let’s adjust our route to invoke an action instead:

  1. # config/routes.rb
  3. module Bookshelf
  4.   class Routes < Hanami::Routes
  5.     root to: "home.show"
  6.   end
  7. end

If we run our test again, we’ll see a Hanami::Routes::MissingActionError:

  1. Failures:
  3.   1) Root is successful
  4.      Failure/Error: get "/"
  6.      Hanami::Routes::MissingActionError:
  7.        Could not find action with key "actions.home.show" in Bookshelf::App
  9.        To fix this, define the action class Bookshelf::Actions::Home::Show in app/actions/home/show.rb
  10.      # ./spec/requests/root_spec.rb:5:in `block (2 levels) in <top (required)>'
  12. Finished in 0.01871 seconds (files took 0.62516 seconds to load)
  13. 1 example, 1 failure

As this error suggests, we need to create the home show action the route is expecting to be able to call.

Hanami provides an action generator we can use to create this action. Running this command will create the home show action:

  1. bundle exec hanami generate action home.show

We can find this action in our app directory at app/actions/home/show.rb:

  1. # app/actions/home/show.rb
  3. module Bookshelf
  4.   module Actions
  5.     module Home
  6.       class Show < Bookshelf::Action
  7.         def handle(*, response)
  8.           response.body = self.class.name
  9.         end
  10.       end
  11.     end
  12.   end
  13. end

In a Hanami application, every action is an individual class. Actions decide what HTTP response (body, headers and status code) to return for a given request.

Actions define a #handle method which accepts a request object, representing the incoming request, and a response object, representing the outgoing response.

  1. def handle(request, response)
  2.   # ...
  3. end

In the automatically generated home show action above, * is used for the request argument because the action does not currently use the request.

For now, let’s adjust our home action to return our desired “Welcome to Bookshelf” message.

  1. # app/actions/home/show.rb
  3. module Bookshelf
  4.   module Actions
  5.     module Home
  6.       class Show < Bookshelf::Action
  7.         def handle(*, response)
  8.           response.body = "Welcome to Bookshelf"
  9.         end
  10.       end
  11.     end
  12.   end
  13. end

With this change, our root spec will now pass:

  1. bundle exec rspec spec/requests/root_spec.rb
  4. Root
  5.   is successful
  7. Finished in 0.03029 seconds (files took 0.72932 seconds to load)
  8. 1 example, 0 failures

As the next step in our bookshelf project, let’s add the ability to display an index of all books in the system, delivered as a JSON API.

First we’ll create a request spec for listing books that expects a successful JSON formatted response, listing two books:

  1. # spec/requests/books/index_spec.rb
  3. RSpec.describe "GET /books", type: :request do
  4.   it "returns a list of books" do
  5.     get "/books"
  7.     expect(last_response).to be_successful
  8.     expect(last_response.content_type).to eq("application/json; charset=utf-8")
  10.     response_body = JSON.parse(last_response.body)
  12.     expect(response_body).to eq([
  13.       { "title" => "Test Driven Development" },
  14.       { "title" => "Practical Object-Oriented Design in Ruby" }
  15.     ])
  16.   end
  17. end

If you run this test, you’ll see that it fails because our application currently returns a 404 response for the /books route.

Let’s fix that by generating an action for a books index:

  1. bundle exec hanami generate action books.index

In addition to generating an action at app/actions/books/index.rb, the generator has also added a route in config/routes.rb:

  1. module Bookshelf
  2.   class Routes < Hanami::Routes
  3.     root to: "home.index"
  4.     get "/books", to: "books.index"
  5.   end
  6. end

If we run our spec again, our expectation for a successful response is now satisfied, but there’s a different failure:

Our response doesn’t have the expected format. Let’s adjust our action to return a JSON formatted response using response.format = :json. We’ll also set the response body to what our test expects:

  1. # app/actions/books/index.rb
  3. module Bookshelf
  4.   module Actions
  5.     module Books
  6.       class Index < Bookshelf::Action
  7.         def handle(*, response)
  8.           books = [
  9.             {title: "Test Driven Development"},
  10.             {title: "Practical Object-Oriented Design in Ruby"}
  11.           ]
  13.           response.format = :json
  14.           response.body = books.to_json
  15.         end
  16.       end
  17.     end
  18.   end
  19. end

If we run our spec, it now passes!

  1. bundle exec rspec spec/requests/books/index_spec.rb
  3. GET /books
  4.   returns a list of books
  6. Finished in 0.02378 seconds (files took 0.49411 seconds to load)
  7. 1 example, 0 failures

Persisting books

Of course, returning a static list of books is not particularly useful.

Let’s address this by retrieving books from a database.

Integrated support for peristence based on rom-rb is coming in Hanami’s 2.1 release. For now, we can bring our own simple rom-rb configuration to allow us to store books in a database.

Let’s add just enough rom-rb to get persistence working using Postgres.

First, add these gems to the Gemfile and run bundle install:

  1. # Gemfile
  2. gem "rom", "~> 5.3"
  3. gem "rom-sql", "~> 3.6"
  4. gem "pg"
  6. group :test do
  7.   gem "database_cleaner-sequel"
  8. end

If you do not have Postgres installed, you can install it using Homebrew, or by following the installation instruction on the PostgreSQL website.

With Postgres running, create databases for development and test using PostgreSQL’s createdb command:

  1. createdb bookshelf_development
  2. createdb bookshelf_test

In Hanami, offer a mechanism for configuring and using dependencies, like databases, within your application.

Copy and paste the following provider into a new file at config/providers/persistence.rb:

  1. Hanami.app.register_provider :persistence, namespace: true do
  2.   prepare do
  3.     require "rom"
  5.     config = ROM::Configuration.new(:sql, target["settings"].database_url)
  7.     register "config", config
  8.     register "db", config.gateways[:default].connection
  9.   end
  11.   start do
  12.     config = target["persistence.config"]
  14.     config.auto_registration(
  15.       target.root.join("lib/bookshelf/persistence"),
  16.       namespace: "Bookshelf::Persistence"
  17.     )
  19.     register "rom", ROM.container(config)
  20.   end
  21. end

For this persistence provider to function, we need to establish a database_url setting.

Settings in Hanami are defined by a Settings class in config/settings.rb:

  1. # config/settings.rb
  3. module Bookshelf
  4.   class Settings < Hanami::Settings
  5.     # Define your app settings here, for example:
  6.     #
  7.     # setting :my_flag, default: false, constructor: Types::Params::Bool
  8.   end
  9. end

Settings can be strings, booleans, integers and other types. Each setting can be either optional or required (meaning the app won’t boot without them), and each can also have a default.

Each setting is sourced from an environment variable matching its name. For example my_flag will be source from ENV["MY_FLAG"].

You can read more about Hanami’s settings in the Application guide.

Let’s add database_url and make it a required setting by using the Types::String constructor:

  1. # config/settings.rb
  3.   class Settings < Hanami::Settings
  4.     # Define your app settings here, for example:
  5.     #
  6.     # setting :my_flag, default: false, constructor: Types::Params::Bool
  8.     setting :database_url, constructor: Types::String
  9.   end

Our bookshelf application will now raise an invalid settings error when it boots, unless a DATABASE_URL environment variable is present.

In development and test environments, Hanami uses the to load environment variables from .env files.

We can now create .env and .env.test files in order to set database_url appropriately in development and test environments:

  1. # .env
  2. DATABASE_URL=postgres://postgres:postgres@localhost:5432/bookshelf_development
  1. # .env.test
  2. DATABASE_URL=postgres://postgres:postgres@localhost:5432/bookshelf_test

You might need to adjust these connection strings based on your local postgres configuration.

To confirm that the database_url setting is working as expected, you can run bundle exec hanami console to start a console, then call the database_url method on your application’s settings object.

  1. bundle exec hanami console
  1. bookshelf[development]> Hanami.app["settings"].database_url
  2. => "postgres://postgres:postgres@localhost:5432/bookshelf_development"

And in test:

  1. HANAMI_ENV=test bundle exec hanami console
  1. bookshelf[test]> Hanami.app["settings"].database_url
  2. => "postgres://postgres:postgres@localhost:5432/bookshelf_test"

To ensure the database is cleaned between tests, add the following to a spec/support/database_cleaner.rb file:

  1. # spec/support/database_cleaner.rb
  3. require "database_cleaner-sequel"
  5. Hanami.app.prepare(:persistence)
  6. DatabaseCleaner[:sequel, db: Hanami.app["persistence.db"]]
  8. RSpec.configure do |config|
  9.   config.before(:suite) do
  10.     DatabaseCleaner.strategy = :transaction
  11.     DatabaseCleaner.clean_with(:truncation)
  12.   end
  14.   config.around(:each, type: :database) do |example|
  15.     DatabaseCleaner.cleaning do
  16.       example.run
  17.     end
  18.   end
  19. end

And then append the following line to spec/spec_helper.rb:

  1. require_relative "support/database_cleaner"

Finally, enable rom-rb’s rake tasks for database migrations by appending the following to the Rakefile:

  1. # Rakefile
  3. require "rom/sql/rake_task"
  5. task :environment do
  6.   require_relative "config/app"
  7.   require "hanami/prepare"
  8. end
  10. namespace :db do
  11.   task setup: :environment do
  12.     Hanami.app.prepare(:persistence)
  13.     ROM::SQL::RakeSupport.env = Hanami.app["persistence.config"]
  14.   end
  15. end

Hanami’s 2.1 release, slated for early 2023, will bring persistence as a first class feature, after which none of the above set up will be required.

With persistence ready, we can now create a books table.

To create a migration run:

  1. bundle exec rake db:create_migration[create_books]

Edit the migration file in order to create a books table with title and author columns and a primary key:

  1. # db/migrate/20221113050928_create_books.rb
  3. ROM::SQL.migration do
  4.   change do
  5.     create_table :books do
  6.       primary_key :id
  7.       column :title, :text, null: false
  8.       column :author, :text, null: false
  9.     end
  10.   end
  11. end

Migrate both the development and test databases:

  1. bundle exec rake db:migrate
  2. HANAMI_ENV=test bundle exec rake db:migrate

Lastly, let’s add a rom-rb relation to allow our application to interact with our books table. Create the following file at lib/bookshelf/persistence/relations/books.rb:

  1. # lib/bookshelf/persistence/relations/books.rb
  3. module Bookshelf
  4.   module Persistence
  5.     module Relations
  6.       class Books < ROM::Relation[:sql]
  7.         schema(:books, infer: true)
  8.       end
  9.     end
  10.   end
  11. end

Listing books

  1. RSpec.describe "GET /books", type: [:request, :database] do
  2.   let(:books) { app["persistence.rom"].relations[:books] }
  4.   before do
  5.     books.insert(title: "Practical Object-Oriented Design in Ruby", author: "Sandi Metz")
  6.     books.insert(title: "Test Driven Development", author: "Kent Beck")
  7.   end
  9.   it "returns a list of books" do
  10.     get "/books"
  12.     expect(last_response).to be_successful
  13.     expect(last_response.content_type).to eq("application/json; charset=utf-8")
  15.     response_body = JSON.parse(last_response.body)
  17.     expect(response_body).to eq([
  18.       { "title" => "Practical Object-Oriented Design in Ruby", "author" => "Sandi Metz" },
  19.       { "title" => "Test Driven Development", "author" => "Kent Beck" }
  20.     ])
  21.   end
  22. end

To get this spec to pass, we’ll need to update our books index action to return books from the books relation.

To access the books relation within the action, we can use Hanami’s “Deps mixin”. Covered in detail in the container and components section of the Architecture guide, the Deps mixin gives each of your application’s components easy access to the other components it depends on to achieve its work. We’ll see this in more detail as these guides progress.

For now however, it’s enough to know that we can use include Deps["persistence.rom"] to make rom-rb available via a rom method within our action. The books relation is then available via rom.relations[:books].

To satisfy our spec, we need to meet a few requirements. Firstly, we want to render each book’s title and author, but not its id. Secondly we want to return books alphabetically by title. We can achieve these requirements using the select and order methods offered by the books relation:

  1. module Bookshelf
  2.   module Actions
  3.     module Books
  4.       class Index < Bookshelf::Action
  5.         include Deps["persistence.rom"]
  7.         def handle(*, response)
  8.           books = rom.relations[:books]
  9.             .select(:title, :author)
  10.             .order(:title)
  11.             .to_a
  13.           response.format = :json
  14.           response.body = books.to_json
  15.         end
  16.       end
  17.     end
  18.   end
  19. end

Accessing relations directly from actions is not a commonly recommended pattern. Instead, a should be used. Here, however, the repository is ommitted for brevity. Hanami’s 2.1 release will offer repositories out of the box.

With this action in place, the spec passes once more:

Of course, returning every book in the database when a visitor makes a request to /books is not going to be a good strategy for very long. Luckily rom-rb relations offer pagination support. Let’s add pagination with a default page size of 5:

  1. # lib/bookshelf/persistence/relations/books.rb
  3. module Bookshelf
  4.   module Persistence
  5.     module Relations
  6.       class Books < ROM::Relation[:sql]
  7.         schema(:books, infer: true)
  9.         use :pagination
  10.         per_page 5
  11.       end
  12.     end
  13.   end
  14. end

This will enable our books index to accept page and per_page params.

Let’s add a request spec verifying pagination:

  1. # spec/requests/books/index/pagination_spec.rb
  3. RSpec.describe "GET /books pagination", type: [:request, :database] do
  4.   let(:books) { app["persistence.rom"].relations[:books] }
  6.   before do
  7.     10.times do |n|
  8.       books.insert(title: "Book #{n}", author: "Author #{n}")
  9.     end
  10.   end
  12.   context "given valid page and per_page params" do
  13.     it "returns the correct page of books" do
  14.       get "/books?page=1&per_page=3"
  16.       expect(last_response).to be_successful
  18.       response_body = JSON.parse(last_response.body)
  20.       expect(response_body).to eq([
  21.         { "title" => "Book 0", "author" => "Author 0" },
  22.         { "title" => "Book 1", "author" => "Author 1" },
  23.         { "title" => "Book 2", "author" => "Author 2" }
  24.       ])
  25.     end
  26.   end
  27. end

In our action class, we can use the request object to extract the relevant params from the incoming request, which allows our spec to pass:

  1. # app/actions/books/index.rb
  3. module Bookshelf
  4.   module Actions
  5.     module Books
  6.       class Index < Bookshelf::Action
  7.         include Deps["persistence.rom"]
  9.         def handle(request, response)
  10.           books = rom.relations[:books]
  11.             .select(:title, :author)
  12.             .order(:title)
  13.             .page(request.params[:page] || 1)
  14.             .per_page(request.params[:per_page] || 5)
  15.             .to_a
  17.           response.format = :json
  18.           response.body = books.to_json
  19.         end
  20.       end
  21.     end
  22.   end
  23. end

Accepting parameters from the internet without validation is never a good idea however. Hanami actions offer built-in parameter validation, which we can use here to ensure that both page and per_page are positive integers, and that per_page is at most 100:

  1. # app/actions/books/index.rb
  3. module Bookshelf
  4.   module Actions
  5.     module Books
  6.       class Index < Bookshelf::Action
  7.         include Deps["persistence.rom"]
  9.         params do
  10.           optional(:page).value(:integer, gt?: 0)
  11.           optional(:per_page).value(:integer, gt?: 0, lteq?: 100)
  12.         end
  14.         def handle(request, response)
  15.           halt 422 unless request.params.valid?
  17.           books = rom.relations[:books]
  18.             .select(:title, :author)
  19.             .order(:title)
  20.             .page(request.params[:page] || 1)
  21.             .per_page(request.params[:per_page] || 5)
  22.             .to_a
  24.           response.format = :json
  25.           response.body = books.to_json
  26.         end
  27.       end
  28.     end
  29.   end
  30. end

In this instance, the params block specifies the following:

  • page and per_page are optional parameters
  • if page is present, it must be an integer greater than 0
  • if per_page is present, it must be an integer greater than 0 and less than or equal to 100

At the start of the handle method, the line halt 422 unless request.params.valid? ensures that the action halts and returns 422 Unprocessable if an invalid parameter was given.

A helpful response revealing why parameter validation failed can also be rendered by passing a body when calling halt:

  1. halt 422, {errors: request.params.errors}.to_json unless request.params.valid?
  1. # spec/requests/books/index/pagination_spec.rb
  3. context "given invalid page and per_page params" do
  4.   it "returns a 422 unprocessable response" do
  5.     get "/books?page=-1&per_page=3000"
  7.     expect(last_response).to be_unprocessable
  9.     response_body = JSON.parse(last_response.body)
  11.     expect(response_body).to eq(
  12.       "errors" => {
  13.         "page" => ["must be greater than 0"],
  14.         "per_page" => ["must be less than or equal to 100"]
  15.       }
  16.     )
  17.   end
  18. end

Validating parameters in actions is useful for performing parameter coercion and type validation. More complex domain-specific validations, or validations concerned with things such as uniqueness, however, are usually better performed at layers deeper than your HTTP actions.

You can find more details on actions and parameter validation in the .

Showing a book

In addition to our books index, we also want to provide an endpoint for viewing the details of a particular book.

Let’s specify a /books/:id request that renders a book for a given id, or returns 404 if there’s no book with the provided id.

  1. # spec/requests/books/show_spec.rb
  3. RSpec.describe "GET /books/:id", type: [:request, :database] do
  4.   let(:books) { app["persistence.rom"].relations[:books] }
  6.   context "when a book matches the given id" do
  7.     let!(:book_id) do
  8.       books.insert(title: "Test Driven Development", author: "Kent Beck")
  9.     end
  11.     it "renders the book" do
  12.       get "/books/#{book_id}"
  14.       expect(last_response).to be_successful
  15.       expect(last_response.content_type).to eq("application/json; charset=utf-8")
  17.       response_body = JSON.parse(last_response.body)
  19.       expect(response_body).to eq(
  20.         "id" => book_id, "title" => "Test Driven Development", "author" => "Kent Beck"
  21.       )
  22.     end
  23.   end
  25.   context "when no book matches the given id" do
  26.     it "returns not found" do
  27.       get "/books/#{books.max(:id).to_i + 1}"
  29.       expect(last_response).to be_not_found
  31.       response_body = JSON.parse(last_response.body)
  34.         "error" => "not_found"
  35.       )
  36.     end
  37.   end
  38. end

Because there’s no matching route yet, this spec immediately fails:

  1. GET /books/:id
  2.   when a book matches the given id
  3.     renders the book (FAILED - 1)
  4.   when no book matches the given id
  5.     returns not found (FAILED - 2)
  7. Failures:
  9.   1) GET /books/:id when a book matches the given id renders the book
  10.      Failure/Error: expect(last_response).to be_successful
  11.        expected `#<Rack::MockResponse:0x000000010c9f5788 @original_headers={"Content-Length"=>"9"}, @errors="", @cooki...ms/rack-2.2.4/lib/rack/response.rb:287>, @block=nil, @body=["Not Found"], @buffered=true, @length=9>.successful?` to be truthy, got false
  12.      # ./spec/requests/books/show_spec.rb:14:in `block (3 levels) in <top (required)>'
  13.      # ./spec/support/database_cleaner.rb:15:in `block (3 levels) in <top (required)>'
  14.      # ./spec/support/database_cleaner.rb:14:in `block (2 levels) in <top (required)>'
  16.   2) GET /books/:id when no book matches the given id returns not found
  17.      Failure/Error: expect(last_response.content_type).to eq("application/json; charset=utf-8")
  19.        expected: "application/json; charset=utf-8"
  20.             got: nil
  22.        (compared using ==)
  23.      # ./spec/requests/books/show_spec.rb:30:in `block (3 levels) in <top (required)>'
  24.      # ./spec/support/database_cleaner.rb:15:in `block (3 levels) in <top (required)>'
  25.      # ./spec/support/database_cleaner.rb:14:in `block (2 levels) in <top (required)>'
  27. Finished in 0.05427 seconds (files took 0.88631 seconds to load)
  28. 2 examples, 2 failures

We can use Hanami’s action generator to create both a route and an action. Run:

  1. bundle exec hanami generate action books.show

If you inspect config/routes.rb you will see the generator has automatically added a new get "/books/:id", to: "books.show" route:

  1. # config/routes.rb
  3. module Bookshelf
  4.   class Routes < Hanami::Routes
  5.     root to: "home.index"
  6.     get "/books", to: "books.index"
  7.     get "/books/:id", to: "books.show"
  8.   end
  9. end

We can now edit the new action at app/actions/books/show.rb to add the required behaviour. Here, we use param validation to coerce params[:id] to an integer, render a book if there’s one with a matching primary key, or return a 404 response. With this, our test passes.

  1. # app/actions/books/show.rb
  3. module Bookshelf
  4.   module Actions
  5.     module Books
  6.       class Show < Bookshelf::Action
  7.         include Deps["persistence.rom"]
  9.         params do
  10.           required(:id).value(:integer)
  11.         end
  13.         def handle(request, response)
  14.           book = rom.relations[:books].by_pk(
  15.             request.params[:id]
  16.           ).one
  18.           response.format = :json
  20.           if book
  21.             response.body = book.to_json
  22.           else
  23.             response.status = 404
  24.             response.body = {error: "not_found"}.to_json
  25.           end
  26.         end
  27.       end
  28.     end
  29.   end
  30. end

In addition to the #one method, which will return nil if there’s no book with the requisite id, rom-rb relations also provide a #one! method, which instead raises a ROM::TupleCountMismatchError exception when no record is found.

We can use this to handle 404s via Hanami’s action exception handling: config.handle_exception. This action configuration takes the name of a method to invoke when a particular exception occurs.

Taking this approach allows our handle method to concern itself only with the happy path:

  1. # app/actions/books/show.rb
  3. require "rom"
  5. module Bookshelf
  6.   module Actions
  7.     module Books
  8.       class Show < Bookshelf::Action
  9.         include Deps["persistence.rom"]
  11.         config.handle_exception ROM::TupleCountMismatchError => :handle_not_found
  13.         params do
  14.           required(:id).value(:integer)
  15.         end
  17.         def handle(request, response)
  18.           book = rom.relations[:books].by_pk(
  19.             request.params[:id]
  20.           ).one!
  22.           response.format = :json
  23.           response.body = book.to_json
  24.         end
  26.         private
  28.         def handle_not_found(_request, response, _exception)
  29.           response.status = 404
  30.           response.format = :json
  31.           response.body = {error: "not_found"}.to_json
  32.         end
  33.       end
  34.     end
  35.   end
  36. end

This exception handling behaviour can also be moved into the base Bookshelf::Action class at app/action.rb, meaning that any action inheriting from Bookshelf::Action will handle ROM::TupleCountMismatchError in the same way.

  1. # app/action.rb
  3. # auto_register: false
  4. require "hanami/action"
  6. module Bookshelf
  7.   class Action < Hanami::Action
  8.     config.handle_exception ROM::TupleCountMismatchError => :handle_not_found
  10.     private
  12.     def handle_not_found(_request, response, _exception)
  13.       response.status = 404
  14.       response.format = :json
  15.       response.body = {error: "not_found"}.to_json
  16.     end
  17.   end
  18. end

With its base action configured to handle ROM::TupleCountMismatchError exceptions, the Books::Show action can now be as follows and our spec continues to pass:

  1. # app/actions/books/show.rb
  3. module Bookshelf
  4.   module Actions
  5.     module Books
  6.       class Show < Bookshelf::Action
  7.         include Deps["persistence.rom"]
  9.         params do
  10.           required(:id).value(:integer)
  11.         end
  13.         def handle(request, response)
  14.           book = rom.relations[:books].by_pk(
  15.             request.params[:id]
  16.           ).one!
  18.           response.format = :json
  19.           response.body = book.to_json
  20.         end
  21.       end
  22.     end
  23.   end
  24. end
  1. bundle exec rspec spec/requests/books/show_spec.rb
  3. GET /books/:id
  4.   when a book matches the given id
  5.     renders the book
  6.   when no book matches the given id
  7.     returns not found
  9. Finished in 0.07726 seconds (files took 1.29 seconds to load)
  10. 2 examples, 0 failures

Creating a book

Now that our visitors can list and view books, let’s allow them to create books too.

Here’s a spec for POST requests to the /books path, where it’s expected that only valid requests result in a book being created:

  1. # spec/requests/books/create_spec.rb
  3. RSpec.describe "POST /books", type: [:request, :database] do
  4.   let(:request_headers) do
  5.     {"HTTP_ACCEPT" => "application/json", "CONTENT_TYPE" => "application/json"}
  6.   end
  8.   context "given valid params" do
  9.     let(:params) do
  10.       {book: {title: "Practical Object-Oriented Design in Ruby", author: "Sandi Metz"}}
  11.     end
  13.     it "creates a book" do
  14.       post "/books", params.to_json, request_headers
  16.       expect(last_response).to be_created
  17.     end
  18.   end
  20.   context "given invalid params" do
  21.     let(:params) do
  22.       {book: {title: nil}}
  23.     end
  25.     it "returns 422 unprocessable" do
  26.       post "/books", params.to_json, request_headers
  28.       expect(last_response).to be_unprocessable
  29.     end
  30.   end
  31. end

Executing this spec, we get the message Method Not Allowed, because there’s no route or action for handling this request.

Hanami’s action generator can add these for us:

  1. bundle exec hanami generate action books.create

The application’s routes now include the expected route - invoking the books.create action for POST requests to /books:

  1. module Bookshelf
  2.   class Routes < Hanami::Routes
  3.     root to: "home.index"
  4.     get "/books", to: "books.index"
  5.     get "/books/:id", to: "books.show"
  6.     post "/books", to: "books.create"
  7.   end
  8. end

And Hanami has generated an action at app/actions/books/create.rb:

  1. # app/actions/books/create.rb
  3. module Bookshelf
  4.   module Actions
  5.     module Books
  6.       class Create < Bookshelf::Action
  7.         def handle(*, response)
  8.           response.body = self.class.name
  9.         end
  10.       end
  11.     end
  12.   end
  13. end

To enable convenient parsing of params from JSON request bodies, Hanami includes a body parser middleware that can be enabled through a config option on the app class. Enable it by adding the following to the Bookshelf::App class in config/app.rb:

  1. # config/app.rb
  3. require "hanami"
  5. module Bookshelf
  6.   class App < Hanami::App
  7.     config.middleware.use :body_parser, :json
  8.   end
  9. end

With this parser in place, the book key from the JSON body will be available in the action via request.params[:book].

We can now complete our create action by inserting a record into the books relation if the posted params are valid:

  1. module Bookshelf
  2.   module Actions
  3.     module Books
  4.       class Create < Bookshelf::Action
  5.         include Deps["persistence.rom"]
  7.         params do
  8.           required(:book).hash do
  9.             required(:title).filled(:string)
  10.             required(:author).filled(:string)
  11.           end
  12.         end
  14.         def handle(request, response)
  15.           if request.params.valid?
  16.             book = rom.relations[:books].changeset(:create, request.params[:book]).commit
  18.             response.status = 201
  19.             response.body = book.to_json
  20.           else
  21.             response.status = 422
  22.             response.format = :json
  23.             response.body = request.params.errors.to_json
  24.           end
  25.         end
  26.       end
  27.     end
  28.   end
  29. end

Our request spec now passes!

  1. bundle exec rspec spec/requests/books/create_spec.rb
  3. POST /books
  4.   given valid params
  5.     creates a book
  6.   given invalid params
  7.     returns 422 unprocessable
  9. 2 examples, 0 failures

In addition to validating title and author are present, the params block in the action also serves to prevent mass assignment - params not included in the schema (for example an attempt to inject a price of 0) will be discarded.

So far we’ve seen how to create a new Hanami application, explored some of the basics of how an application is structured, and seen how we can list, display and create a simple book entity while validating user input.

Still, we’ve barely touched the surface of what Hanami offers.