add Host, Version and Secure options to replace URL (c27f079a) · Commits · Roman Lacko / gitlab_api

GitLab/API.pm

+85 −20

Original line number	Diff line number	Diff line
		@@ -40,7 +40,15 @@ sub croak(@) { $log->fatal(@_); Carp::croak @_; }
		sub new {
		my ($class, %args) = @_;

		croak "URL parameter is required" unless defined $args{URL};
		croak "either URL or Host parameter is required, but not both"
		unless (defined $args{URL} xor defined $args{Host});

		if (defined $args{Host}) {
		my $s = ($args{Secure} // 1) ? "https" : "http";
		my $v = $args{Version} // 4;
		$args{URL} = "$s://$args{Host}/api/v$v";
		}

		$log->debug("initializing GitLab::API for \"$args{URL}\"");

		my $self = {
		@@ -422,7 +430,7 @@ See L<GitLab API\|http://doc.gitlab.com/ce/api/> for details.

		my $gitlab = GitLab::API->new(
		AuthToken => $token,
		URL => $url,
		Host => $host,
		);

		# simple result
		@@ -452,24 +460,81 @@ See L<GitLab API\|http://doc.gitlab.com/ce/api/> for details.

		Creates a new instance of L<GitLab::API>. Takes a hash of arguments:

		Login user login
		Email user e-mail, required only if Login is not provided,
		Password user password
		AuthToken authentication token
		URL url to connect to, usually https://gitlab.domain/api/v3
		DieOnError see die_on_error() method
		Cache enable caching
		=over

		=item * Host specification

		Either C<URL> or C<Host> is required, but not both.

		=over

		=item C<URL>

		Fully specifies the API to connect to. Usually in format
		L<http(s)://gitlab.domain.com/api/v4>. Must not be combined with C<Host>.

		=item C<Host>

		Hostname of GitLab. Must not be combined with C<URL>.

		=item C<Version>

		Version of GitLab API to connect to. The default is C<4> and you should
		not change this unless you really need other versions.
		This options is ignored if C<URL> is used.

		=item C<Secure>

		Whether or not use HTTPS. The default is C<1>.
		This option is ignored if C<URL> is used.

		=back

		=item * Login information

		There are three ways to log in to GitLab, using a combination of parameters:

		C<URL> is always required.
		The method also requires I<either> C<AuthToken> I<or> ((C<Login> or C<Email>) and C<Password>).
		That is, the only meaningful combinations are
		=over

		=item C<AuthToken>

		Use GitLab Personal Token to access API. Does not need to use the Session
		API, hence avoids one step when setting up L<GitLab::API>.

		=item C<Login>, C<Password>

		This combination will use Session API to obtain token. Then it will
		continue as C<AuthToken> was specified.

		=item C<Email>, C<Password>

		An alternative to C<Login> and C<Password>.

		=back

		=item * Miscellaneous

		GitLab::API->new(URL => $URL, AuthToken => $TOKEN);
		GitLab::API->new(URL => $URL, Login => $LOGIN, Password => $PASSWD);
		GitLab::API->new(URL => $URL, Email => $EMAIL, Password => $PASSWD);
		=over

		=item C<DieOnError>

		API will call L<Carp/croak> if any request fails. This general option
		can be overriden when needed, by setting C<< -immortal => 1 >> to request.

		=item C<Cache>

		API will use L<GitLab::API::Cache> to store data along with their C<ETags>
		to speed up repetitive requests. This may, however, consume more memory.
		You may manually clear the cache by calling

		Caching is available since version L<9.0.0> and allows to cache responses
		based on C<ETag> headers. See L<GitLab::API::Cache> for more details.
		$gitlab->cache->flush;

		The ETags are fully supported in GitLab since version 9.0.0. If L<GitLab::API>
		detects that GitLab is of earlier version, a warning will be logged.

		=back

		=back

		=item sudo()

		@@ -480,9 +545,9 @@ Similar to L<sudo(8)\|sudo>, changes identity to the user with the C<$username>.
		If the C<$username> argument is not defined, changes the identity back to the original user.

		I<This feature is available only to the admins.>
		You can test for that with the L</whoami> method this way:
		You can test for that with the L</is_admin> method like this:

		if ($gitlab->whoami()->{is_admin}) {
		if ($gitlab->is_admin) {
		# Booyah!
		}

		@@ -507,7 +572,7 @@ The result is not affected by L</sudo()>.
		my $value = $gitlab->die_on_error();
		$gitlab->die_on_error($value);

		When called without an argument, returns the current value of the settings.
		When called without an argument, returns the current value of the setting.
		Otherwise sets the first argument as the value.

		If enabled, any call that returns an unsuccessful (!= 2**) HTTP code will call C<Carp/croak> with the status code.