view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

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' },