view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

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

# SYNOPSIS

```perl
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](https://metacpan.org/pod/GitLab%3A%3AAPI%3A%3Av4).

# 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](http://doc.gitlab.com/ce/api/README.html).

Note that this distribution also includes the [gitlab-api-v3](https://metacpan.org/pod/gitlab-api-v3) command-line
interface (CLI).

# CREDENTIALS

Authentication credentials may be defined by setting either the ["token"](#token),
the ["login"](#login) and ["password"](#password), or the ["email"](#email) and ["password"](#password) arguments.

When the object is constructed the ["login"](#login), ["email"](#email), and ["password"](#password)
arguments are used to call ["session"](#session) to generate a token.  The token is
saved in the ["token"](#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](https://metacpan.org/pod/GitLab%3A%3AAPI%3A%3Av3%3A%3AConstants).

## 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](https://metacpan.org/pod/Try%3A%3ATiny).

## LOGGING

This module uses [Log::Any](https://metacpan.org/pod/Log%3A%3AAny) 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"](#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"](#login) or ["email"](#email) may be set.
Read more in ["CREDENTIALS"](#credentials).

## login

A GitLab user login name.
If set then ["password"](#password) must be set.
Read more in ["CREDENTIALS"](#credentials).

## email

A GitLab user email.
If set then ["password"](#password) must be set.
Read more in ["CREDENTIALS"](#credentials).

## password

A GitLab user password.
This must be set if either ["login"](#login) or ["email"](#email) are set.
Read more in ["CREDENTIALS"](#credentials).

## rest\_client

An instance of [GitLab::API::v3::RESTClient](https://metacpan.org/pod/GitLab%3A%3AAPI%3A%3Av3%3A%3ARESTClient).  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

```perl
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](https://metacpan.org/pod/GitLab%3A%3AAPI%3A%3Av3%3A%3APaginator)
object that will allow you to walk the records one page or one record
at a time.

# AWARD EMOJI METHODS

See [http://docs.gitlab.com/ce/api/award\_emoji.html](http://docs.gitlab.com/ce/api/award_emoji.html).

## issue\_award\_emojis

```perl
my $award_emojis = $api->issue_award_emojis(
    $id,
    $issue_id,
);
```

Sends a `GET` request to `/projects/:id/issues/:issue_id/award_emoji` and returns the decoded/deserialized response body.

## merge\_request\_award\_emojis

```perl
my $award_emojis = $api->merge_request_award_emojis(