Guide · Open source

How to use Grape: build a REST-like API in Ruby

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Grape is an open-source framework for building REST-like APIs in Ruby. It runs on Rack and can also sit alongside existing apps such as Rails and Sinatra. This guide shows how to add it to a project, define endpoints with its small DSL, and mount the API in a running application.

Graperuby-grape/grape · ★ 10k · MIT Install options & downloads

Quick start

1Check your Ruby version. Confirm you have Ruby 3.3.1 or newer, since the README lists it as a requirement.
2Add the gem. Run bundle add grape in your project directory to add Grape to your Gemfile.
3Create an API class. Subclass Grape::API in a Ruby file and set format and any version or prefix options.
4Define endpoints. Write get, post, put or delete blocks inside the class, using params blocks to declare required inputs.
5Mount or run the API. Run it from config.ru with rackup, or mount it in Rails config/routes. Call compile! to pre-load routes if you want.
6Combine with other frameworks if needed. Use Rack::Cascade to run Grape beside Sinatra, placing Grape last so its 404 errors are handled correctly.

Install Grape in your Ruby project

Grape is distributed as a gem and requires Ruby 3.3.1 or newer. Add it to your project with Bundler from the project directory.

Check that your Ruby version is 3.3.1 or newer before you start.
Grape is installed through your Gemfile, so your project needs Bundler.

bundle add grape

Define an API by subclassing Grape::API

Grape APIs are Rack applications created by subclassing `Grape::API`. The README's example recreates parts of the Twitter API. It sets a version and a JSON format, adds a prefix, and groups endpoints into a `resource`.

Each HTTP verb is written as a method such as `get`, `post`, `put` or `delete`. A `params` block declares required inputs with their types, and `helpers` define shared methods such as authentication checks.

`version 'v1', using: :header, vendor: 'twitter'` sets versioning.
`format :json` sets the response format.
`prefix :api` puts every route under `/api`.
`route_param :id` defines routes that take an ID in the path.

module Twitter
  class API < Grape::API
    version 'v1', using: :header, vendor: 'twitter'
    format :json
    prefix :api

    resource :statuses do
      desc 'Return a public timeline.'
      get :public_timeline do
        Status.limit(20)
      end
    end
  end
end

Mount the API with Rack or config.ru

A Grape API can be run from a rackup `config.ru` file with `rackup`. You can pre-load routes with `compile!`; otherwise Grape compiles them on the first request. Grape also responds to HEAD and OPTIONS automatically for GET routes, and to OPTIONS for other routes.

Without pre-loading, routes compile on the first request.
With pre-loading, call `compile!` before `run`.

Twitter::API.compile!
run Twitter::API

Run Grape alongside Sinatra or another framework

To mount Grape next to another Rack framework such as Sinatra, use `Rack::Cascade`. The order matters: the Grape application must be listed last if you want custom 404 errors from Grape, such as `error!('Not Found',404)`. If Grape is not last and returns a 404 or 405, Cascade moves on to the next app.

Put Grape last in `Rack::Cascade.new [Web, API]`.
Otherwise you may see the wrong 404 page from the wrong app.

run Rack::Cascade.new [Web, API]

Add Grape to a Rails app

Place API files in `app/api`. Rails expects a directory matching the module name and a file matching the class name, so `Twitter::API` lives in `app/api/twitter/api.rb`. Then mount it in `config/routes`.

Rails' default autoloader, Zeitwerk, inflects `api` as `Api`. To fix this, uncomment the lines at the bottom of `config/initializers/inflections.rb` and add `API` as an acronym.

Mount the API with `mount Twitter::API => '/'` in `config/routes`.
Grape's deprecator is added automatically as `:grape` in Rails 7.1.

ActiveSupport::Inflector.inflections(:en) do |inflect|
  inflect.acronym 'API'
end

Split an API into mountable modules

You can mount several API implementations inside one another. They do not have to be different versions; they can be components of the same API. You can also mount a module at a path, which works like `prefix`.

Declarations such as `before`, `after` and `rescue_from` can go before or after `mount` and are inherited by the mounted APIs. Endpoints can also be remounted in more than one location, and mount configuration lets the same code behave differently depending on where it is mounted.

`mount Twitter::APIv1 => '/v1'` mounts a module under a path.
Remounted endpoints can be reached at each mount location.
Passing a hash as the first argument to `mount` requires parentheses.

class Twitter::API < Grape::API
  mount Twitter::APIv1
  mount Twitter::APIv2
end

What people use it for

Building a REST-style JSON API for a Ruby backend.
Adding an API layer to an existing Rails or Sinatra application.
Splitting a large API into mountable components, such as separate user and search modules.
Serving multiple API versions from one codebase using versioning options.

Frequently asked questions

How do I install Grape?

Grape is installed as a Ruby gem. Run `bundle add grape` in your project directory. The README says Ruby 3.3.1 or newer is required.

Is Grape free to use?

Grape is released under the MIT licence, according to its repository. The maintainers also offer commercial support through a Tidelift subscription, which is optional.

What Ruby version does Grape need?

The README states that Ruby 3.3.1 or newer is required. Check your version before adding the gem.

Can Grape work with Rails?

Yes. Place API files in app/api, follow the Rails naming convention, and mount the API in config/routes. You also need to add the API acronym to the Zeitwerk inflections.

Can I run Grape and Sinatra in the same app?

Yes, using Rack::Cascade. Put the Grape application last in the list so that its custom 404 errors are not overridden by another app.

Is Grape a good choice for a full website with pages?

Not really. Grape focuses on APIs and does not provide views or front-end pages, so a full web app with HTML pages is better built with a framework like Rails.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Grape suits Ruby developers who need a REST-style JSON API, or teams adding an API beside an existing Rails or Sinatra app. It is a poor fit for non-Ruby teams, for people who need views and front-end pages, or for beginners without Ruby experience, since the README assumes familiarity with Rack and Ruby classes. Frameworks such as Sinatra, Rails API mode, Roda or Hanami API are the alternatives to compare.

Install options & downloads