In order to understand what the requested MIME Type is, an action looks at the request header and exposes a high level API: #format and #accept?.

The first returns a symbol representation of the MIME Type (eg. :html, :json, :xml etc..), while the second is a query method that accepts a MIME type string and checks if it’s accepted by the current browser.

An action returns the Content-Type response header automatically according to the requested MIME Type and charset.

If a client asks for a generic Accept: */*, the action will fall back to the application default format. This is a setting that allows us to safely handle cases like our example; the default value is :html.

# apps/web/application.rb
module Web
  class Application < Hanami::Application
    configure do
      # ...
    end
  end

If we are building a JSON API app, it can be useful to specify a :json as default MIME Type for the response. The default value is :html.

Similarly, we can specify a different default charset to return. The standard value is utf-8, but we can change it in our settings.

# apps/web/application.rb
module Web
  class Application < Hanami::Application
    configure do
      # ...
      default_charset 'koi8-r'
    end
  end
end

The example above will return Content-Type: application/json; charset=utf-8.

We can also restrict the range of accepted MIME Types. If the incoming request doesn’t satisfy this constraint, the application will return a Not Acceptable status (406).

  module Controllers
    module Dashboard
      class Index
        include Web::Action
        accept :html, :json
        def call(params)
          # ...
        end
      end
    end
  end

Hanami knows about more than 100 of the most common MIME types. However, we may want to add custom types in order to use them with #format= or .accept.