Hanami::API

Minimal, extremely fast, lightweight Ruby framework for HTTP APIs.

• Home page: http://hanamirb.org
• Mailing List: http://hanamirb.org/mailing-list
• API Doc: http://rubydoc.info/gems/hanami-api
• Bugs/Issues: https://github.com/hanami/api/issues
• Chat: http://chat.hanamirb.org

Hanami::API supports Ruby (MRI) 3.2+

Add these lines to your application's Gemfile:

gem "hanami-api"
gem "puma" # or "webrick", or "thin", "falcon"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install hanami-api

• Performance
  • Runtime
  • Memory
  • Requests per second
• Usage
  • Routes
  • HTTP methods
  • Endpoints
    • Rack endpoint
    • Block endpoint
      • String (body)
      • Enumerator (body)
      • Integer (status code)
      • Integer, String (status code, body)
      • Integer, Enumerator (status code, body)
      • Integer, Hash, String (status code, headers, body)
      • Integer, Hash, Enumerator (status code, headers, body)
  • Block context
    • env
    • status
    • headers
    • body
    • params
    • halt
    • redirect
    • back
    • json
  • Scope
  • Helpers
  • Rack Middleware
  • Streamed Responses
  • Body Parsers
• Testing
• Development
• Contributing

Benchmark against an app with 10,000 routes, hitting the 10,000th to measure the worst case scenario. Based on jeremyevans/r10k, Hanami::API scores first for speed, and second for memory footprint.

Runtime to complete 20,000 requests (lower is better).

Memory footprint for 10,000 routes app (lower is better).

For this benchmark there are two apps for each framework: one with the root route, and one with 10,000 routes. Requests per second hitting the 1st (and only route) and the 10,000th route to measure the best and worst case scenario (higher is better).

Create config.ru at the root of your project:

# frozen_string_literal: true

require "bundler/setup"
require "hanami/api"

class App < Hanami::API
  get "/" do
    "Hello, world"
  end
end

run App.new

Start the Rack server with bundle exec rackup

A route is a combination of three elements:

• HTTP method (e.g. get)
• Path (e.g. "/")
• Endpoint (e.g. MyEndpoint.new)

get "/", to: MyEndpoint.new

Hanami::API supports the following HTTP methods:

• get
• head
• post
• patch
• put
• delete
• options
• trace
• link
• unlink

Hanami::API supports two kind of endpoints: block and Rack.

The framework is compatible with Rack. Any Rack endpoint, can be passed to the route:

get "/", to: MyRackEndpoint.new

A block passed to the route definition is named a block endpoint. The returning value will compose the Rack response. It can be:

get "/" do
  "Hello, world"
end

It will return [200, {}, ["Hello, world"]]

get "/" do
  Enumerator.new { ... }
end

It will return [200, {}, Enumerator], see Streamed Responses

get "/" do
  418
end

It will return [418, {}, ["I'm a teapot"]]

get "/" do
  [401, "You shall not pass"]
end

It will return [401, {}, ["You shall not pass"]]

get "/" do
  [401, Enumerator.new { ... }]
end

It will return [401, {}, Enumerator], see Streamed Responses

get "/" do
  [401, {"X-Custom-Header" => "foo"}, "You shall not pass"]
end

It will return [401, {"X-Custom-Header" => "foo"}, ["You shall not pass"]]

get "/" do
  [401, {"X-Custom-Header" => "foo"}, Enumerator.new { ... }]
end

It will return [401, {"X-Custom-Header" => "foo"}, Enumerator], see Streamed Responses

When using the block syntax there is a rich API to use.

The #env method exposes the Rack environment for the current request

Get HTTP status

get "/" do
  puts status
    # => 200
end

Set HTTP status

get "/" do
  status(201)
end

Get HTTP response headers

get "/" do
  puts headers
    # => {}
end

Set HTTP status

get "/" do
  headers["X-My-Header"] = "OK"
end

Get HTTP response body

get "/" do
  puts body
    # => nil
end

Set HTTP response body

get "/" do
  body "Hello, world"
end

Set HTTP response body using a Streamed Response

get "/" do
  body Enumerator.new { ... }
end

Access params for current request

get "/" do
  id = params[:id]
  # ...
end

Halts the flow of the block and immediately returns with the current HTTP status

get "/authenticate" do
  halt(401)

  # this code will never be reached
end

It sets a Rack response: [401, {}, ["Unauthorized"]]

get "/authenticate" do
  halt(401, "You shall not pass")

  # this code will never be reached
end

It sets a Rack response: [401, {}, ["You shall not pass"]]

You can also use a Streamed Response here

get "/authenticate" do
  halt(401, Enumerator.new { ... })
end

Redirects request and immediately halts it

get "/legacy" do
  redirect "/dashboard"

  # this code will never be reached
end

It sets a Rack response: [301, {"Location" => "/new"}, ["Moved Permanently"]]

get "/legacy" do
  redirect "/dashboard", 302

  # this code will never be reached
end

It sets a Rack response: [302, {"Location" => "/new"}, ["Moved"]]

Utility for redirect back using HTTP request header HTTP_REFERER

get "/authenticate" do
  if authenticate(env)
    redirect back
  else
    # ...
  end
end

Sets a JSON response for the given object

get "/user/:id" do
  user = UserRepository.new.find(params[:id])
  json(user)
end

get "/user/:id" do
  user = UserRepository.new.find(params[:id])
  json(user, "application/vnd.api+json")
end

If you want a Streamed Response

get "/users" do
  users = Enumerator.new { ... }
  json(users)
end

Prefixing routes is possible with routing scopes:

scope "api" do
  scope "v1" do
    get "/users", to: Actions::V1::Users::Index.new
  end
end

It will generate a route with "/api/v1/users" as path.

Define helper methods available within the block context. Helper methods have access to default utilities available in block context (e.g. #halt).

Helpers can be defined inline by passing a block to the .helpers method:

require "hanami/api"

class MyAPI < Hanami::API
  helpers do
    def redirect_to_root
      # redirect method is provided by Hanami::API block context
      redirect "/"
    end
  end

  root { "Hello, World" }

  get "/legacy" do
    redirect_to_root
  end
end

Alternatively, .helpers accepts a module.

require "hanami/api"

class MyAPI < Hanami::API
  module Authentication
    private

    def unauthorized
      halt(401)
    end
  end

  helpers(Authentication)

  root { "Hello, World" }

  get "/secrets" do
    unauthorized
  end
end

You can use .helpers multiple times in the same app.

To mount a Rack middleware it's possible with .use

# frozen_string_literal: true

require "bundler/setup"
require "hanami/api"

class App < Hanami::API
  use ElapsedTime

  scope "api" do
    use ApiAuthentication

    scope "v1" do
      use ApiV1Deprecation
    end

    scope "v2" do
      # ...
    end
  end
end

Middleware are inherited from top level scope.

In the example above, ElapsedTime is used for each incoming request because it's part of the top level scope. ApiAuthentication it's used for all the API versions, because it's defined in the "api" scope. ApiV1Deprecation is used only by the routes in "v1" scope, but not by "v2".

When the work to be done by the server takes time, it may be a good idea to stream your response. For this, you just use an Enumerator anywhere you would normally use a String as body or another Object as JSON response. Here's an example of streaming JSON data:

scope "stream" do
  use ::Rack::Chunked

  get "/data" do
    Enumerator.new do |yielder|
      data = %w[a b c]
      data.each do |item|
        yielder << item
      end
    end
  end

  get "/to_enum" do
    %w[a b c].to_enum
  end

  get "/json" do
    result = Enumerator.new do |yielder|
      data = %w[a b c]
      data.each do |item|
        yielder << item
      end
    end

    json(result)
  end
end

Note:

• Returning an Enumerator will also work without Rack::Chunked, it just won't stream but return the whole body at the end instead.
• Data pushed to yielder MUST be a String.
• Streaming does not work with WEBrick as it buffers its response. We recommend using puma, though you may find success with other servers.
• To manual test this feature use a web browser or cURL:

$ curl --raw -i http://localhost:2300/stream/data

Rack ignores request bodies unless they come from a form submission. If you have an endpoint that accepts JSON, the request payload isn’t available in params.

In order to parse JSON payload and make it avaliable in params, you should add the following lines to config.ru:

# frozen_string_literal: true
require "hanami/middleware/body_parser"

use Hanami::Middleware::BodyParser, :json

You can unit test your Hanami::API app by passing a env hash to your app's #call method.

The keys that (based on the Rack standard) Hanami::API uses for routing are:

• PATH_INFO
• REQUEST_METHOD

For example, a spec for the basic app in the Usage section could be:

require "my_project/app"

RSpec.describe App do
  describe "#call" do
    it "returns successfully" do
      response = subject.call({"PATH_INFO" => "/", "REQUEST_METHOD" => "GET"})
      expect(response).to eq([200, {}, ["Hello, world"]])
    end
  end
end

Add this line to your application's Gemfile:

gem "rack-test", group: :test

In a test, load Rack::Test:

require "rack/test"

and then, inside your spec/test, include its helper methods:

include Rack::Test::Methods

Then you can use its methods like get and last_response, e.g.:

it "returns the status 200" do
  get "/"
  expect(last_response.status).to eq 200
end

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/hanami/api.

Copyright © 2014–2024 Hanami Team – Released under MIT License.