NAME

GitLab::API::v3 - A complete GitLab API v3 client. (deprecated)

SYNOPSIS

use GitLab::API::v3;

my $api = GitLab::API::v3->new(
    url   => $v3_api_url,
    token => $token,
);

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

DEPRECATED

This module is at the end of it's life as the latest GitLab no longer supports the v3 API. Instead, use GitLab::API::v4.

DESCRIPTION

This module provides a one-to-one interface with the GitLab API v3. 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-v3 command-line interface (CLI).

CREDENTIALS

Authentication credentials may be defined by setting either the "token", the "login" and "password", or the "email" and "password" arguments.

When the object is constructed the "login", "email", and "password" arguments are used to call "session" to generate a token. The token is saved in the "token" attribute, and the login/email/password arguments are discarded.

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

CONSTANTS

Several values in the GitLab API require looking up the numeric value for a meaning (such as access_level and visibility_level). Instead of doing that, you can use GitLab::API::v3::Constants.

EXCEPTIONS

The API methods will all throw (hopefully) 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 either a numeric project ID, or as a NAMESPACE_PATH/PROJECT_PATH in many cases. Perhaps even all cases, but the GitLab documentation on this point is vague.

RETURN VALUES

Many of this module's methods should return a value but do not currently. This is due to the fact that this module was built as a strict representation of GitLab's own documentation which is often inconsistent.

If you find a method that should provide a return value, but doesn't currently, please verify that GitLab actually does return a value and then submit a pull request or open an issue. See "CONTRIBUTING" for more info.

REQUIRED ARGUMENTS

url

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

OPTIONAL ARGUMENTS

token

A GitLab API token. If set then neither "login" or "email" may be set. Read more in "CREDENTIALS".

login

A GitLab user login name. If set then "password" must be set. Read more in "CREDENTIALS".

email

A GitLab user email. If set then "password" must be set. Read more in "CREDENTIALS".

password

A GitLab user password. This must be set if either "login" or "email" are set. Read more in "CREDENTIALS".

rest_client

An instance of GitLab::API::v3::RESTClient. Typically you will not be setting this as it defaults to a new instance and customization should not be necessary.

retries

The number of times the request should be retried in case it does not succeed. Defaults to 0, meaning that a failed request will not be retried.

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::v3::Paginator object that will allow you to walk the records one page or one record at a time.