Hanami::API
Minimal, extremely fast, lightweight Ruby framework for HTTP APIs.
Version
This branch contains the code for hanami-api
0.3.x.
Status
Contact
- Home page: http://hanamirb.org
- Mailing List: http://hanamirb.org/mailing-list
- API Doc: http://rdoc.info/gems/hanami-api
- Bugs/Issues: https://github.com/hanami/api/issues
- Support: http://stackoverflow.com/questions/tagged/hanami
- Chat: http://chat.hanamirb.org
Rubies
Hanami::API supports Ruby (MRI) 3.0+
Installation
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
- Usage
- Testing
- Development
- Contributing
Performance
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
Runtime to complete 20,000 requests (lower is better).
Framework | Seconds to complete |
---|---|
hanami-api | 0.116 |
watts | 0.235 |
roda | 0.348 |
syro | 0.356 |
rack-app | 0.623 |
cuba | 1.291 |
rails | 17.047 |
sinatra | 197.477 |
Memory
Memory footprint for 10,000 routes app (lower is better).
Framework | Bytes |
---|---|
roda | 47252 |
hanami-api | 53988 |
cuba | 55420 |
syro | 60256 |
rack-app | 82976 |
watts | 84956 |
sinatra | 124980 |
rails | 143048 |
Requests per second
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).
Framework | 1st route | 10,000th route |
---|---|---|
hanami-api | 14719.95 | 14290.20 |
watts | 13912.31 | 12609.68 |
roda | 13965.20 | 11051.27 |
syro | 13079.12 | 10689.51 |
rack-app | 10274.01 | 10306.46 |
cuba | 13061.82 | 7084.33 |
rails | 1345.27 | 303.06 |
sinatra | 5038.74 | 28.14 |
Usage
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
Routes
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
HTTP methods
Hanami::API
supports the following HTTP methods:
get
head
post
patch
put
delete
options
trace
link
unlink
Endpoints
Hanami::API
supports two kind of endpoints: block and Rack.
Rack endpoint
The framework is compatible with Rack. Any Rack endpoint, can be passed to the route:
get "/", to: MyRackEndpoint.new
Block endpoint
A block passed to the route definition is named a block endpoint. The returning value will compose the Rack response. It can be:
String (body)
get "/" do
"Hello, world"
end
It will return [200, {}, ["Hello, world"]]
Enumerator (body)
get "/" do
Enumerator.new { ... }
end
It will return [200, {}, Enumerator]
, see Streamed Responses
Integer (status code)
get "/" do
418
end
It will return [418, {}, ["I'm a teapot"]]
Integer, String (status code, body)
get "/" do
[401, "You shall not pass"]
end
It will return [401, {}, ["You shall not pass"]]
Integer, Enumerator (status code, body)
get "/" do
[401, Enumerator.new { ... }]
end
It will return [401, {}, Enumerator]
, see Streamed Responses
Integer, Hash, String (status code, headers, body)
get "/" do
[401, {"X-Custom-Header" => "foo"}, "You shall not pass"]
end
It will return [401, {"X-Custom-Header" => "foo"}, ["You shall not pass"]]
Integer, Hash, Enumerator (status code, headers, body)
get "/" do
[401, {"X-Custom-Header" => "foo"}, Enumerator.new { ... }]
end
It will return [401, {"X-Custom-Header" => "foo"}, Enumerator]
, see Streamed Responses
Block context
When using the block syntax there is a rich API to use.
env
The #env
method exposes the Rack environment for the current request
status
Get HTTP status
get "/" do
puts status
# => 200
end
Set HTTP status
get "/" do
status(201)
end
headers
Get HTTP response headers
get "/" do
puts headers
# => {}
end
Set HTTP status
get "/" do
headers["X-My-Header"] = "OK"
end
body
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
params
Access params for current request
get "/" do
id = params[:id]
# ...
end
halt
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
redirect
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"]]
back
Utility for redirect back using HTTP request header HTTP_REFERER
get "/authenticate" do
if authenticate(env)
redirect back
else
# ...
end
end
json
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
Scope
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.
Helpers
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.
Rack Middleware
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"
.
Streamed Responses
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 withoutRack::Chunked
, it just won't stream but return the whole body at the end instead. - Data pushed to
yielder
MUST be aString
. - 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
Body Parsers
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
Testing
Unit testing
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
Integration testing
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
Development
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.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/hanami/api.
Copyright
Copyright ยฉ 2014-2022 Hanami Team โ Released under MIT License.