Jason Charnes

Hanami Routes - Learn Hanami #2

By this point, you should have Hanami installed on your computer with an empty Hanami application named blog ready to go. Today, you’ll learn how Hanami routes work.

Routes are the entry point to your web application. A router is used to tell your application where to send an incoming request. Under the hood, Hanami routes use Hanami Router. According to the documentation, Hanami’s router is a:

Rack compatible, lightweight and fast HTTP Router for Ruby and Hanami.


Hanami, like any good Ruby web framework, is built on Rack. Without going too deep into Rack, imagine it is the glue between the web server and Hanami. Hanami uses Rack to respond to the request the web server received. What Rack is looking for is a response with three parts:

  • The HTTP response code
  • A Hash of HTTP headers
  • The response body (which must respond to `#each`)

This information is important because the first route the Hanami documentation shows you to add is a raw response that Rack knows how to handle.

Your First Route

Open apps/web/config/routes.rb and add the following route:

get '/', to: ->(env) { [200, {}, ['My new blog!']] }

Before you worry about any specifics of this code, go back to your terminal and run the command we learned in the last lesson to start your application: hanami server

At this point, you should be able to visit http://localhost:2300/ and see a basic web page that only says “My new blog!”

Congrats, you’ve just created your first route with Hanami! So, how does that work?

Remember the three parts that Rack takes? You just provided them to the router (via a lambda) to return when someone visits '/', aka the root of your website. At this point, you’ve told the route to return:

  1. A 200 HTTP Response Code
  2. No headers
  3. The content for the browser to render, which in this case is just some text.

Routing Inside Hanami

Now that you know how the router works with Rack, it’s easier to understand what imagine what happens the response from a route sent to a Hanami controller.

For the blog you’re building, you’ll always be sending incoming requests to what are called Actions. You’ll learn more about actions in the next lesson.

Here is a high-level overview of how the actions work with the router.

  • A request arrives
  • The router finds the action the request should be sent to
  • The action performs
  • A response returns from the action

Any guess what the response might be?

A rack compatible response containing a response code, a hash of headers, and the response body.

Enough with the details, right?!

Hanami Routes

As I mentioned earlier, throughout this series, you’ll be creating routes sent to actions. Delete the previous route you wrote and replace it with this:

get '/', to: 'posts#index'

There are three parts to this route:

get '/', to: 'posts#index'
|- HTTP Verb |- URI |- Action

1. HTTP Verb

The Hanami router can respond to seven different HTTP verbs:

  • GET
  • POST
  • PUT

In the route you created earlier, you declared it would respond to a GET request. You’ll learn more about the different HTTP verbs when you learn about actions. For now, you can read about the various HTTP verbs here.

2. URI

The URI (Uniform Resource Identifier) is in it’s simplest form, the path after your domain.


  • http://example.com/posts
  • http://example.com/posts/123456

In the route you just created, you’re saying tell the router this: “When someone visits the root of my application, direct them here.”

You’ll learn more about the URI and how you can write fewer routes when you learn about actions.

3. The Action

I know, I keep telling about how you’ll learn about actions in a future lesson. That is still true. However, I’m going to give you the high-level overview here.

An action is “the endpoint that handles incoming HTTP requests for a particular route.” An action is responsible for orchestrating what should happen when an HTTP request is sent to it. (Please don’t mistake the word orchestrate for responsible. We’ll cover that when we talk about actions.)

Our first action is responsible for showing a list of blogs posts. Following REST conventions, we’ll create an _index _action for posts. This is where pick up at on the next lesson.

Wrapping Up

Hopefully, at this point, you’re aware of how a route works in Hanami. If you have any questions, feel free to find me on Twitter.

Finally, make sure you use the form below to be the first to get the next lesson.

Follow me on Twitter.