NAME

GitLab::API::v4 - A complete GitLab API v4 client.

SYNOPSIS

use GitLab::API::v4;

my $api = GitLab::API::v4->new(
    url           => $v4_api_url,
    private_token => $token,
);

my $branches = $api->branches( $project_id );

DESCRIPTION

This module provides a one-to-one interface with the GitLab API v4. Much is not documented here as it would just be duplicating GitLab's own API Documentation.

Note that this distribution also includes the gitlab-api-v4 command-line interface (CLI).

Upgrading

If you are upgrading from GitLab::API::v3 make sure you read:

https://docs.gitlab.com/ce/api/v3_to_v4.html

Also, review the Changes file included in the distribution as it outlines the changes made to convert the v3 module to v4:

https://github.com/bluefeet/GitLab-API-v4/blob/master/Changes

Finally, be aware that many methods were added, removed, renamed, and/or altered. If you want to review exactly what was changed you can use GitHub's compare tool:

https://github.com/bluefeet/GitLab-API-v4/compare/72e384775c9570f60f8ef68dee3a1eecd347fb69...master

Or clone the repo and run this command:

git diff 72e384775c9570f60f8ef68dee3a1eecd347fb69..HEAD -- author/sections/

Credentials

Authentication credentials may be defined by setting either the "access_token" or "private_token" arguments.

If no credentials are supplied then the client will be anonymous and greatly limited in what it can do with the API.

Extra care has been taken to hide the token arguments behind closures. This way, if you dump your api object, your tokens won't accidentally leak into places you don't want them to.

Constants

The GitLab API, in rare cases, uses a hard-coded value to represent a state. To make life easier the GitLab::API::v4::Constants module exposes these states as named variables.

Exceptions

The API methods will all throw a useful exception if an unsuccessful response is received from the API. That is except for GET requests that return a 404 response - these will return undef for methods that return a value.

If you'd like to catch and handle these exceptions consider using Try::Tiny.

Logging

This module uses Log::Any and produces some debug messages here and there, but the most useful bits are the info messages produced just before each API call.

Project ID

Note that many API calls require a $project_id. This can be specified as a numeric project ID or, in many cases, maybe all cases, as a NAMESPACE_PATH/PROJECT_PATH string. The GitLab documentation on this point is vague.

REQUIRED ARGUMENTS

url

The URL to your v4 API endpoint. Typically this will be something like https://git.example.com/api/v4.

OPTIONAL ARGUMENTS

access_token

A GitLab API OAuth2 token. If set then "private_token" may not be set.

See https://docs.gitlab.com/ce/api/#oauth2-tokens.

private_token

A GitLab API personal token. If set then "access_token" may not be set.

See https://docs.gitlab.com/ce/api/#personal-access-tokens.

retries

The number of times the request should be retried in case it fails (5XX HTTP response code). Defaults to 0 (false), meaning that a failed request will not be retried.

sudo_user

The user to execute API calls as. You may find it more useful to use the "sudo" method instead.

See https://docs.gitlab.com/ce/api/#sudo.

rest_client

An instance of GitLab::API::v4::RESTClient (or whatever "rest_client_class" is set to). Typically you will not be setting this as it defaults to a new instance and customization should not be necessary.

rest_client_class

The class to use when constructing the "rest_client". Defaults to GitLab::API::v4::RESTClient.

UTILITY METHODS

paginator

my $paginator = $api->paginator( $method, @method_args );

my $members = $api->paginator('group_members', $group_id);
while (my $member = $members->next()) {
    ...
}

my $users_pager = $api->paginator('users');
while (my $users = $users_pager->next_page()) {
    ...
}

my $all_open_issues = $api->paginator(
    'issues',
    $project_id,
    { state=>'opened' },
)->all();

Given a method who supports the page and per_page parameters, and returns an array ref, this will return a GitLab::API::v4::Paginator object that will allow you to walk the records one page or one record at a time.

sudo

$api->sudo('fred')->create_issue(...);

Returns a new instance of GitLab::API::v4 with the "sudo_user" argument set.