REST API

176 Grape files mounted under /api/v4.

Source

lib/api/
├── api.rb                  # API::API root, mounts everything
├── api_guard.rb             # Auth and rate-limiting concerns
├── concerns/                # Shared mixins
├── helpers/                 # Common helper modules
├── entities/                # Grape::Entity definitions for JSON serialization
├── validations/             # Custom validators
├── ci/, projects/, groups/, packages/, ...   # Per-feature subtrees
├── internal/                # See Internal API page
└── ...

EE additions live under ee/lib/api/. They mount additional resources and prepend EE-only behavior onto FOSS classes.

Mounting

API::API (lib/api/api.rb) mounts every endpoint, applies common middleware, and configures error handling. The order matters: more specific paths come first.

Authentication

Every endpoint goes through API::APIGuard (lib/api/api_guard.rb):

1. Read PRIVATE-TOKEN, Authorization: Bearer ..., or session cookie.
2. Call Gitlab::Auth.find_for_git_client (and friends) to validate.
3. Apply scope checks (api, read_api, read_user, read_repository, etc.).
4. Set current_user for the request.

Some endpoints support deploy tokens, CI job tokens, or feed tokens — the guard handles them.

Endpoint structure

A typical Grape file:

module API
  class Projects < ::API::Base
    feature_category :groups_and_projects

    helpers do
      params :update_params do
        # ...
      end
    end

    resource :projects do
      desc 'Get a single project' do
        success Entities::Project
      end
      params do
        requires :id, type: String, desc: 'Project ID or path'
      end
      get ':id' do
        present user_project, with: Entities::Project, current_user: current_user
      end
    end
  end
end

Conventions:

• Declare feature_category at the top.
• Use Entities::* (under lib/api/entities/) for serialization.
• Use present for response shaping and proper N+1 guards.
• Use the :id URL-decoder helper to accept both numeric IDs and group/subgroup/project paths.

Rate limits

Endpoints inherit the request-level rate limit. Hot endpoints declare additional throttles via Gitlab::ApplicationRateLimiter.

Versioning

The REST API has been on v4 since 2017. Breaking changes follow the GitLab REST API deprecation policy. New endpoints are non-breaking additions.

OpenAPI

Some sub-trees are documented with the gitlab-grape-openapi gem. Schema is dumped via bin/rake gitlab:openapi:dump and published to docs.gitlab.com.

Pagination

GitLab's REST API supports keyset and offset pagination:

• Offset (default): ?page=2&per_page=20. Easy but slow on large lists.
• Keyset: ?pagination=keyset&order_by=id&sort=desc. Required on hot endpoints.

Gitlab::Pagination::Keyset::Order (lib/gitlab/pagination/keyset/) provides the implementation.

Errors

Errors are JSON: {"message": "..."}. HTTP status codes follow REST conventions. Validation errors include a message keyed by field name.

Where to make changes

• New endpoint: add to lib/api/<area>.rb (or create a new file and mount in lib/api/api.rb).
• New entity: under lib/api/entities/<area>/.
• New parameter validator: under lib/api/validations/.
• New scope: extend Gitlab::Auth::API_SCOPES in lib/gitlab/auth.rb and document.

Related

• GraphQL API — alternative for newer features.
• Internal API — what other GitLab services call.
• Authentication.