Routes and Namespaces

Grape provides a clean and expressive DSL for defining API routes and organizing them into logical groups called namespaces.

Defining Routes

You can define routes using helper methods for each HTTP verb: get, post, put, patch, delete, head, and options. You can also use route to specify multiple methods at once, or route :any to match any method.

class MyAPI < Grape::API
  # Simple GET request
  get :hello do
    'world'
  end

  # POST request
  post :statuses do
    # ... create a status ...
  end

  # Route that accepts both PUT and PATCH
  route [:put, :patch], ':id' do
    # ... update a resource ...
  end
end

The path can be a String or a Symbol.

Route Parameters

Parts of the path prefixed with a colon (:) are treated as parameters and are available in the params hash.

get 'users/:id' do
  # The value of :id is available in params[:id]
  User.find(params[:id])
end

Namespaces

Namespaces allow you to group related endpoints under a common path prefix and share settings like helpers, middleware, and parameter declarations.

namespace, group, resource, resources, and segment are all aliases for the same functionality.

class MyAPI < Grape::API
  namespace :statuses do
    # This endpoint will be available at GET /statuses/public_timeline
    get :public_timeline do
      # ...
    end

    # Nested namespace
    namespace ':id' do
      # This endpoint will be available at GET /statuses/:id/replies
      get :replies do
        # ...
      end
    end
  end
end

route_param

The route_param helper is a convenient way to define a namespace based on a route parameter, often including type validation.

namespace :statuses do
  route_param :id, type: Integer do
    # GET /statuses/:id
    get do
      Status.find(params[:id])
    end

    # GET /statuses/:id/replies
    get 'replies' do
      Status.find(params[:id]).replies
    end
  end
end

This is equivalent to:

namespace :statuses do
  namespace ':id' do
    params do
      requires :id, type: Integer
    end
    # ... routes ...
  end
end

Route Requirements

You can specify regular expression requirements for route parameters to enforce a specific format at the routing level.

# This route will only match if :id is a number.
get ':id', requirements: { id: /[0-9]*/ } do
  Status.find(params[:id])
end

Describing Your API

You can add metadata to your endpoints using the desc method. This is especially useful for auto-generating documentation with tools like grape-swagger.

desc 'Return a status.' do
  summary 'Finds a single status by its ID.'
  params API::Entities::Status.documentation # Use an entity for param docs
  success API::Entities::Status # Describe the success response entity
  failure [[404, 'Not Found']]
  headers XAuthToken: {
            description: 'Validates your identity',
            required: true
          }
end
params do
  requires :id, type: Integer, desc: 'Status ID.'
end
get ':id' do
  Status.find(params[:id])
end

Allowed Methods (HEAD and OPTIONS)

• HEAD: Grape automatically creates a HEAD route for every GET route. You can disable this behavior globally with do_not_route_head!.
• OPTIONS: Grape automatically creates an OPTIONS route for every path. The response includes an Allow header listing the supported HTTP methods. You can disable this with do_not_route_options!.

If a request is made with an unsupported HTTP method for a given path, Grape returns a 405 Method Not Allowed response.