Mounting a Grape API into Rack, Rails or a Sinatra cascade
An opinionated framework for creating REST-like APIs in Ruby.
At a glance
- What is it?
- Grape turns a subclass of Grape::API into a Rack application with a routing DSL, and it mounts inside Rails or Sinatra without replacing the host router. What it gives up is predictable: 404s that escape a cascade, an inflection that breaks Zeitwerk, and two different stable version numbers on consecutive lines of the same README.
- Who is it for?
- Grape suits teams that already run Ruby web infrastructure and want a JSON surface mounted beside the existing app; it suits them badly if they expect authentication to arrive with the gem. Verify two things before pinning a version: which release is actually stable, given that the README names both 4.2.0 and 4.1.0, and whether your Rack stack places the Grape app last in its cascade.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Ruby, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.
Star history
- ruby-grape/grape10,005 ★ · -2
| Repository | 2026-09-22 | 2026-11-14 |
|---|---|---|
| ruby-grape/grape | 10k | 10k |
-2 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Ruby 3.3.1 is the floor and Bundler does the whole install
Grape ships as a gem and nothing else. The stated requirement is Ruby 3.3.1 or newer, so an older runtime is the first thing to rule out before reading a single line of the DSL.
bundle add grapeThat command is the entire install procedure. Because a Grape API is a Rack application, the first real step is subclassing Grape::API, not configuring a web server:
class API < Grape::API
get :hello do
{ hello: 'world' }
end
endDrop that class into a config.ru beside any other Rack code and rackup will serve it. The return value of the block is the response body, which is why the sample returns a hash instead of calling a render method. Authentication is written the same way, as a helper you define yourself. The Twitter example in the docs puts current_user and authenticate! inside a helpers block, with authenticate! calling error!('401 Unauthorized', 401) when no user is found, so the status code and the body are both yours to choose.
Route compilation waits for the first request unless compile! runs
Grape compiles routes on the first request that arrives, not when the class body is evaluated. The first request therefore pays the compile cost. Pre-loading moves that work to boot:
Twitter::API.compile!The call belongs in config.ru if you use rackup, in application.rb if you use Rails, or in any file that loads your server. After compilation the class answers exactly the routes you declared. With version 'v1', using: :header, vendor: 'twitter', format :json and prefix :api in scope, the example exposes GET /api/statuses/public_timeline, GET /api/statuses/home_timeline, GET /api/statuses/:id, POST /api/statuses, PUT /api/statuses/:id and DELETE /api/statuses/:id. Grape also answers HEAD and OPTIONS for every GET route and OPTIONS only for everything else. Those verbs come from the framework rather than your block, so middleware that counts or filters by HTTP method has to account for them.
A Grape 404 under Rack::Cascade is a signal to try the next app
Running Grape next to Sinatra is one config file, and the order of that file decides whether your own 404 survives.
use Rack::Session::Cookie
run Rack::Cascade.new [Web, API]Put the Grape class last and an error!('Not Found',404) raised inside Grape reaches the client as written. Put it anywhere else and Rack::Cascade reads that 404 or 405 response as a reason to fall through to the next app in the array, so a caller asking for a missing JSON endpoint can be handed the HTML not-found page belonging to the Sinatra side. The README links issue 1515 for exactly this outcome. For a team serving both from one host, the remedy is placement rather than code, which is at least cheap to verify: check the array order before debugging anything else. The failure is quiet in development when both apps render a similar page and only surfaces for a client that parses JSON, which is a bad place to find out your cascade is misordered.
Zeitwerk reads API as Api, so the Rails constant never resolves
Mounting under Rails imposes a file layout before it imposes any code. An API belongs in app/api, in a subdirectory matching the module and a filename matching the class, so Twitter::API has to live at app/api/twitter/api.rb. Then config/routes takes one line:
mount Twitter::API => '/'Rails loads classes through Zeitwerk by default, and Zeitwerk inflects api as Api rather than API. Until you correct that, the example does not work. The fix belongs at the bottom of config/initializers/inflections.rb, where the lines need uncommenting, with the acronym added:
ActiveSupport::Inflector.inflections(:en) do |inflect|
inflect.acronym 'API'
endThat edit is global to the application, so any other class named with API gains the same inflection. On Rails 7.1, Grape's own deprecator is added to your application's deprecators as :grape automatically through lib/grape/railtie.rb, which means your application deprecation configuration applies to Grape without any wiring on your side.
The stable README names 4.1.0 and links 4.0.1
Two version numbers sit on consecutive lines near the top of the README. One sentence tells you the documentation covers the stable release, which should be 4.2.0. The next sentence calls 4.1.0 the current stable release and links to that tag's README. Anyone pinning a gem has to choose between them, and the document does not say which number wins. The repository carries no GitHub releases, so there is no release page to settle the argument either. Version history sits in the tree instead: CHANGELOG.md, UPGRADING.md and RELEASING.md at the root, the last of which describes how a release is cut. Planning a jump between the two versions means opening UPGRADING.md yourself. The last push landed on 2026-11-01. The license is MIT, and the README offers commercial support and maintenance through a Tidelift subscription; otherwise it points at the issue tracker.
A remounted endpoint reads its configuration at the mount site
One API class can be mounted inside another, optionally under a path:
class Twitter::API < Grape::API
mount Twitter::APIv1 => '/v1'
endThe same class can also be mounted twice. A Voting::API holding a votes namespace, mounted from Post::API and from Comment::API, answers get /posts/votes, post /posts/votes, get /comments/votes and post /comments/votes from a single body of code. To let the two mount points differ, the endpoint reads configuration while its description is built:
desc "Vote for your #{configuration[:votable]}"Because the description is built from the mount configuration, the description served under /posts/votes and under /comments/votes can differ without duplicating the handler. One more wrinkle: a parent may declare before, after and rescue_from blocks either side of a mount call and they are inherited in both positions.
The repository carries lint, coverage, benchmark and container tooling
The top level tells you how the project is worked on: .rubocop.yml, .rspec and .simplecov for the test and coverage setup, .coveralls.yml and a Dangerfile for pull request checks, AGENTS.md, SECURITY.md, gemfiles/ for the dependency matrix, benchmark/ for performance work, and docker/Dockerfile wired up by docker-compose.yml. Compose builds that image and mounts the working tree and a gem volume:
build:
context: .
dockerfile: docker/Dockerfile
args:
- RUBY_VERSION=${RUBY_VERSION:-4.0}The default there is 4.0, well above the 3.3.1 floor stated for installation, so a contributor container and a deployed runtime are not pinned to the same Ruby by anything visible in this repository.
Editorial conclusion
Grape suits teams that already run Ruby web infrastructure and want a JSON surface mounted beside the existing app; it suits them badly if they expect authentication to arrive with the gem. Verify two things before pinning a version: which release is actually stable, given that the README names both 4.2.0 and 4.1.0, and whether your Rack stack places the Grape app last in its cascade. Read UPGRADING.md and CHANGELOG.md at the repository root first, since the repository has no GitHub releases.
Frequently asked questions
What Ruby version does Grape require?
The README states Ruby 3.3.1 or newer is required. Grape is distributed as a gem and is added with bundle add grape.
How do I mount Grape next to a Sinatra app without losing my own 404 page?
Place the Grape application last in the Rack::Cascade array. If it is not last and returns a 404 or 405, the cascade uses that as a signal to try the next app, which can show the wrong app's 404 page. The README links issue 1515 for this behavior.
Why does Grape answer HEAD and OPTIONS routes I never declared?
Grape automatically responds to HEAD and OPTIONS for all GET routes, and to OPTIONS only for all other routes.
Does Grape work with Rails autoloading?
Yes, with one adjustment. Zeitwerk inflects api as Api instead of API, so you add API as an acronym in config/initializers/inflections.rb and place the API file at app/api/twitter/api.rb for a Twitter::API class.
Can Grape compile its routes before the first request?
By default routes compile on the first request. Calling compile! preloads them, and that call can go in config.ru, application.rb or any file that loads your server.
How do I mount the same Grape endpoints in two places?
Mount the same API class from more than one parent class. A Voting::API mounted under Post::API and Comment::API then serves get and post on /posts/votes and /comments/votes.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/ruby-grape-grape)Star history chart for your README
[](https://hysenlabs.com/projects/ruby-grape-grape)Was this useful?