REST API, GraphQL API, Webhooks, System Hooks, Pagination, Rate Limits, and Automation: Concepts, Architecture, and Mental Model

1. The practical problem: automation fails at boundaries, not only syntax

A script that works for ten resources can silently miss the eleventh page. A webhook receiver can accept forged JSON because the payload shape looks correct. A GraphQL request can return HTTP 200 while the response still contains authorization errors. A retry loop can create the same object twice. Chapter 29 treats GitLab automation as a distributed-systems problem: identity, resource scope, pagination, delivery semantics, rate limits, idempotency, and evidence all matter.

2. Mental model: clients, API authority, and event delivery

REST exposes resource-oriented endpoints under the versioned /api/v4 base path. GraphQL exposes a typed schema where one request can traverse related objects and mutations return structured payloads. glab api is a convenient authenticated client for either surface. Webhooks reverse the direction: GitLab initiates an HTTP delivery to your receiver when configured events occur.

flowchart TD
  U[Automation client] -->|REST /api/v4| R[GitLab REST resources]
  U -->|GraphQL query or mutation| G[GitLab GraphQL schema]
  CLI[glab / glab api] --> R
  CLI --> G
  R --> P[Project or group state]
  G --> P
  P -->|project/group webhook| W[External receiver]
  I[Instance events] -->|system hook| W
  W --> V[Verify signature and timestamp]
  V --> D[Deduplicate webhook-id]
  D --> Q[Queue / process action]

The external receiver is a new trust boundary. Network arrival is not authentication. Verify the current signing mechanism before parsing or acting on the event, reject stale timestamps, deduplicate retries, and decouple acknowledgment from slow downstream work.

3. REST: resource URLs, status codes, and explicit identity

The canonical REST base path is https://HOST/api/v4. Use documented project/group IDs or URL-encoded paths and inspect HTTP status plus response body. A 401 means authentication failed; 403 normally means the authenticated identity is not authorized; 404 can intentionally hide a resource you cannot see; 409 often represents a state conflict; 429 means a rate limit was enforced.

# Read-only examples from an authenticated project checkout.
glab api projects/:fullpath \
  | jq '{id,path_with_namespace,default_branch,visibility}'

glab api -i "projects/:fullpath/labels?per_page=20"

For raw clients, access tokens are normally sent using the documented PRIVATE-TOKEN header (or Bearer where supported). CI job tokens use JOB-TOKEN only on endpoints that explicitly support them. Prefer the narrowest short-lived identity available for the operation.

4. GraphQL: typed selection, cursor pagination, and two error layers

GraphQL is useful when consumers need a shaped view across related GitLab objects. Connections typically use Relay-style cursor pagination. Request pageInfo { hasNextPage endCursor }, then pass the returned cursor as after. Do not infer a numeric “next page.”

query($fullPath: ID!, $endCursor: String) {
  project(fullPath: $fullPath) {
    issues(first: 20, after: $endCursor) {
      nodes { iid title state }
      pageInfo { hasNextPage endCursor }
    }
  }
}

Transport success is not application success. Inspect top-level errors. Mutations can also expose errors inside their payload. An unexpected field value of null may indicate insufficient permission, while an authorized empty connection is represented as an object whose nodes list is empty.

5. glab api: convenient client, same server-side authority

glab api accepts a REST v4 path or the literal endpoint graphql. In a Git repository it can infer the authenticated GitLab host and repository placeholders such as :fullpath; outside a repository it defaults to GitLab.com unless --hostname is supplied. For reproducible automation, make the intended host/project explicit whenever ambiguity is possible.

glab api projects/:fullpath --output json

glab api graphql \
  -f query='query { currentUser { username } }'

# For list automation, prefer structured output and documented pagination.
glab api projects/:fullpath/issues --paginate --output ndjson

6. Pagination is correctness, not an optimization detail

Do not use x-total or x-total-pages as an invariant: GitLab.com can omit pagination headers and large responses can omit totals for performance. Completion is determined by the documented next-link/cursor mechanism.

7. Webhooks: authenticate before parsing, then deduplicate

Project webhooks are Free-compatible. Group webhooks are Premium/Ultimate. GitLab 19.1 made the HMAC-SHA256 signing-token mechanism generally available and recommends it for new webhooks. A signed delivery includes webhook-id, webhook-timestamp, and webhook-signature. The signature covers the message ID, timestamp, and exact body bytes. Validate timestamp freshness before accepting the event.

Retries/redelivery mean “at least once” is the safer consumer model. The stable webhook ID lets a receiver make duplicate delivery a no-op. Do not assume two different events arrive in business order; reconcile current GitLab state if ordering matters.

8. System hooks are not “bigger project webhooks”

System hooks are administrator-managed instance integrations for broad instance events. Current feature documentation covers Self-Managed and Dedicated; the current System Hooks REST API reference is Self-Managed-specific. This distinction matters: a project Maintainer should not design a production integration that assumes instance-administrator API access exists on every offering.

9. Rate limits and retry policy

When GitLab enforces a request rate limit it returns 429. Depending on the limit/installation, responses can expose RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and on 429 Retry-After. Not every application-specific limit is represented by the generic headers, so a client must handle 429 even if a previous response seemed to have remaining capacity.

10. The production automation loop

flowchart TD
  O[Observe current state] --> C{Change required?}
  C -->|No| N[No-op and record evidence]
  C -->|Yes| M[Mutate once]
  M --> V[Read back state]
  V --> S{Desired state reached?}
  S -->|Yes| E[Record sanitized audit evidence]
  S -->|No| B[Classify error / bounded retry if safe]
  B --> O

Idempotency is a design property: running the client twice should leave one desired resource, not two. Preserve request IDs, resource IDs, selected response metadata, and the before/after state so an operator can explain what changed without storing credentials.

Knowledge check

11. Summary and next bridge

You now have the authority and reliability model. Lesson 2 turns it into a disposable lab: paginated REST, cursor-based GraphQL, a locally signed/replayed synthetic webhook, and one harmless desired-state label mutation.

Primary sources and version notes

These lessons were finalized against current official GitLab documentation on 2026-08-22. API fields, rate limits, webhook event schemas, CLI flags, and tier/offering availability can change, so production clients should pin/document assumptions and re-check the API/CLI documentation for the deployed GitLab version.

• GitLab 19.3 release
• REST API
• REST API authentication
• REST API troubleshooting
• GraphQL API
• Run GraphQL queries and mutations
• glab api
• GitLab CLI authentication
• Webhooks
• Webhook events
• System hooks
• System Hooks API
• User and IP rate limits
• Project labels API