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).

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).

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

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

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.

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.

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

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