---
title: GitLab API Client
---

# Specification: GitLab API Client

## Purpose

Provides network access to GitLab's REST API and exposes high-level operations consumed by the data-collection layer (see [Data Collector](./spec_data_collector.md)).

---

## 1. Endpoint Responsibilities

| Operation | HTTP method & path | Successful response type | Notes |
|-----------|-------------------|--------------------------|-------|
| List groups | `GET /api/v4/groups` | JSON array of group objects | Supports pagination via default GitLab parameters; client must collate all pages and return a complete list. |
| List projects for group | `GET /api/v4/groups/{groupId}/projects` | JSON array of project objects | Same pagination handling as above. |
| Fetch project file (raw) | `GET /api/v4/projects/{projectId}/repository/files/{encodedPath}/raw?ref={branch}` | Raw text | `branch` is caller-supplied; defaults to repository's default branch when unknown. |
| List issues for project | `GET /api/v4/projects/{projectId}/issues` | JSON array of issue objects | User must provide key with auth scope capable of reading issues. |

> *Encoded path* = URL-encoded full file path (e.g. `README.md`).

---

## 2. Configuration / Authentication

* On construction the Client takes a `gitlab_host` and `group_api_key` as configuration.
* Calls go to `{gitlab_host}{path from 1.}`.
* Authentication is done via the `Bearer {group_api_key}` header

---

## 3. Error-to-Exception Mapping

| HTTP status | Raised exception |
|-------------|-----------------|
| 401 / 403 | Authentication error |
| 404 | Not-found error |
| 429 | Rate-limit error |
| Any other 4xx/5xx | Generic GitLab API error |

All exceptions propagate *as-is* to callers; the client must not swallow them.

---

## 4. Retry Strategy

* Retries are governed by two numeric settings: *max attempts* and *exponential back-off (seconds)*.
* Non-idempotent requests are not retried.
* Only retry on network errors or status codes 429 and ≥ 500.

---

## 5. Resource Management

* Provides an explicit `close()` (or context-manager support) that disposes the underlying HTTP connection pool.
* Callers must close the client after use to avoid open sockets.

---

## 6. Thread-Safety

No thread-safety guarantees are required; concurrent usage is caller's responsibility.

---

## 7. Non-Goals

* Does not perform business logic such as filtering inactive projects – that is handled by higher layers.