V1.3: RESTful Resource(s)

Hanami has native REST support.

At the routing level, there are two methods that can be used to declare them: resources and resource. The former is for plural resources, the latter for singular ones.

Declaring a resource means to generate several default routes with just one line of code.

RESTful Resources

Default Routes

# apps/web/config/routes.rb
resources :books

It generates:

Remove Routes

In case we don’t need all the default routes we can use :only and pass one or more action names. We can also black list routes with :except.

resources :books, only: [:new, :create, :show]

# equivalent to

resources :books, except: [:index, :edit, :update, :destroy]

Add Routes

Alongside with default routes we can specify extra routes for single (member) or multiple (collection) resources.

resources :books do
  member do
    # Generates /books/1/toggle, maps to Books::Toggle, named :toggle_book
    get 'toggle'
  end

  collection do
    # Generates /books/search, maps to Books::Search, named :search_books
    get 'search'
  end
end

Configure Controller

Imagine we have a controller named manuscripts, where we have actions like Manuscripts::Index, but we still want to expose those resources as /books. Using the :controller option will save our day.

resources :books, controller: 'manuscripts'

# GET /books/1 will route to Manuscripts::Show, etc.

RESTful Resource

resource :account

It generates:

Remove Routes

resource :account, only: [:show, :edit, :update, :destroy]

# equivalent to

resource :account, except: [:new, :create]

Add Routes

resource :account do
  member do
    # Generates /account/avatar, maps to Account::Avatar, named :avatar_account
    get 'avatar'
  end

  collection do
    # Generates /account/authorizations, maps to Account::Authorizations, named :authorizations_account
    get 'authorizations'
  end
end

Configure Controller

resource :account, controller: 'customer'

Nested Resource(s)

RESTful resource(s) can be nested in order to make available inner resources inside the scope of their parents.

Plural to plural

resources :books do
  resources :reviews
end

It generates default routes for books and the following ones.

Plural to singular

resources :books do
  resource :cover
end

It generates default routes for books and the following ones.

Singular To Plural

resource :account do
  resources :api_keys
end

It generates default routes for account and the following ones.

Singular To Singular

resource :account do
  resource :avatar
end

It generates default routes for account and the following ones.