# Hanami::API Minimal, extremely fast, lightweight Ruby framework for HTTP APIs. ## Version **This branch contains the code for `hanami-api` 0.3.x.** ## Status [![Gem Version](https://badge.fury.io/rb/hanami-api.svg)](https://badge.fury.io/rb/hanami-api) [![CI](https://github.com/hanami/api/workflows/ci/badge.svg?branch=main)](https://github.com/hanami/api/actions?query=workflow%3Aci+branch%3Amain) [![Test Coverage](https://codecov.io/gh/hanami/api/branch/main/graph/badge.svg)](https://codecov.io/gh/hanami/api) [![Depfu](https://badges.depfu.com/badges/a8545fb67cf32a2c75b6227bc0821027/overview.svg)](https://depfu.com/github/hanami/api?project=Bundler) [![Inline Docs](http://inch-ci.org/github/hanami/api.svg)](http://inch-ci.org/github/hanami/api) ## 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`: ```ruby gem "hanami-api" gem "puma" # or "webrick", or "thin", "falcon" ``` And then execute: ```shell $ bundle install ``` Or install it yourself as: ```shell $ gem install hanami-api ``` * [Performance](#performance) + [Runtime](#runtime) + [Memory](#memory) + [Requests per second](#requests-per-second) * [Usage](#usage) + [Routes](#routes) + [HTTP methods](#http-methods) + [Endpoints](#endpoints) - [Rack endpoint](#rack-endpoint) - [Block endpoint](#block-endpoint) * [String (body)](#string-body) * [Enumerator (body)](#enumerator-body) * [Integer (status code)](#integer-status-code) * [Integer, String (status code, body)](#integer-string-status-code-body) * [Integer, Enumerator (status code, body)](#integer-enumerator-status-code-body) * [Integer, Hash, String (status code, headers, body)](#integer-hash-string-status-code-headers-body) * [Integer, Hash, Enumerator (status code, headers, body)](#integer-hash-enumerator-status-code-headers-body) + [Block context](#block-context) - [env](#env) - [status](#status) - [headers](#headers) - [body](#body) - [params](#params) - [halt](#halt) - [redirect](#redirect) - [back](#back) - [json](#json) + [Scope](#scope) + [Helpers](#helpers) + [Rack Middleware](#rack-middleware) + [Streamed Responses](#streamed-responses) + [Body Parsers](#body-parsers) * [Testing](#testing) * [Development](#development) * [Contributing](#contributing) ## Performance Benchmark against an app with 10,000 routes, hitting the 10,000th to measure the worst case scenario. Based on [`jeremyevans/r10k`](https://github.com/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: ```ruby # 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`) ```ruby 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: ```ruby 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) ```ruby get "/" do "Hello, world" end ``` It will return `[200, {}, ["Hello, world"]]` ##### Enumerator (body) ```ruby get "/" do Enumerator.new { ... } end ``` It will return `[200, {}, Enumerator]`, see [Streamed Responses](#streamed-responses) ##### Integer (status code) ```ruby get "/" do 418 end ``` It will return `[418, {}, ["I'm a teapot"]]` ##### Integer, String (status code, body) ```ruby get "/" do [401, "You shall not pass"] end ``` It will return `[401, {}, ["You shall not pass"]]` ##### Integer, Enumerator (status code, body) ```ruby get "/" do [401, Enumerator.new { ... }] end ``` It will return `[401, {}, Enumerator]`, see [Streamed Responses](#streamed-responses) ##### Integer, Hash, String (status code, headers, body) ```ruby 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) ```ruby get "/" do [401, {"X-Custom-Header" => "foo"}, Enumerator.new { ... }] end ``` It will return `[401, {"X-Custom-Header" => "foo"}, Enumerator]`, see [Streamed Responses](#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 ```ruby get "/" do puts status # => 200 end ``` Set HTTP status ```ruby get "/" do status(201) end ``` #### headers Get HTTP response headers ```ruby get "/" do puts headers # => {} end ``` Set HTTP status ```ruby get "/" do headers["X-My-Header"] = "OK" end ``` #### body Get HTTP response body ```ruby get "/" do puts body # => nil end ``` Set HTTP response body ```ruby get "/" do body "Hello, world" end ``` Set HTTP response body using a [Streamed Response](#streamed-responses) ```ruby get "/" do body Enumerator.new { ... } end ``` #### params Access params for current request ```ruby get "/" do id = params[:id] # ... end ``` #### halt Halts the flow of the block and immediately returns with the current HTTP status ```ruby get "/authenticate" do halt(401) # this code will never be reached end ``` It sets a Rack response: `[401, {}, ["Unauthorized"]]` ```ruby 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](#streamed-responses) here ```ruby get "/authenticate" do halt(401, Enumerator.new { ... }) end ``` #### redirect Redirects request and immediately halts it ```ruby get "/legacy" do redirect "/dashboard" # this code will never be reached end ``` It sets a Rack response: `[301, {"Location" => "/new"}, ["Moved Permanently"]]` ```ruby 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` ```ruby get "/authenticate" do if authenticate(env) redirect back else # ... end end ``` #### json Sets a JSON response for the given object ```ruby get "/user/:id" do user = UserRepository.new.find(params[:id]) json(user) end ``` ```ruby get "/user/:id" do user = UserRepository.new.find(params[:id]) json(user, "application/vnd.api+json") end ``` If you want a [Streamed Response](#streamed-responses) ```ruby get "/users" do users = Enumerator.new { ... } json(users) end ``` ### Scope Prefixing routes is possible with routing scopes: ```ruby 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: ```ruby 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. ```ruby 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` ```ruby # 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: ```ruby 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: ```shell $ 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`: ```ruby # 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](https://github.com/hanami/api#usage) could be: ```ruby 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`: ```ruby gem "rack-test", group: :test ``` In a test, load `Rack::Test`: ```ruby require "rack/test" ``` and then, inside your spec/test, include its helper methods: ```ruby include Rack::Test::Methods ``` Then you can use its methods like `get` and `last_response`, e.g.: ```ruby 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](https://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.