xphoon/GitLab-API-v3

A complete GitLab API v3 client.

NAME

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

SYNOPSIS

use GitLab::API::v3;

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

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

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).

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.

token

A GitLab API token.

OPTIONAL ARGUMENTS

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.

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.

USER METHODS

See http://doc.gitlab.com/ce/api/users.html.

users

my $users = $api->users(
    \%params,
);

Sends a GET request to /users and returns the decoded/deserialized response body.

user

$api->user(
    $user_id,
);

Sends a GET request to /users/:user_id.

create_user

$api->create_user(
    \%params,
);

Sends a POST request to /users.

edit_user

$api->edit_user(
    $user_id,
    \%params,
);

Sends a PUT request to /users/:user_id.

delete_user

my $user = $api->delete_user(
    $user_id,
);

Sends a DELETE request to /users/:user_id and returns the decoded/deserialized response body.

current_user

my $user = $api->current_user();

Sends a GET request to /user and returns the decoded/deserialized response body.

current_user_ssh_keys

my $keys = $api->current_user_ssh_keys();

Sends a GET request to /user/keys and returns the decoded/deserialized response body.

user_ssh_keys

my $keys = $api->user_ssh_keys(
    $user_id,
);

Sends a GET request to /users/:user_id/keys and returns the decoded/deserialized response body.

user_ssh_key

my $key = $api->user_ssh_key(
    $key_id,
);

Sends a GET request to /user/keys/:key_id and returns the decoded/deserialized response body.

create_current_user_ssh_key

$api->create_current_user_ssh_key(
    \%params,
);

Sends a POST request to /user/keys.

create_user_ssh_key

$api->create_user_ssh_key(
    $user_id,
    \%params,
);

Sends a POST request to /users/:user_id/keys.

delete_current_user_ssh_key

$api->delete_current_user_ssh_key(
    $key_id,
);

Sends a DELETE request to /user/keys/:key_id.

delete_user_ssh_key

$api->delete_user_ssh_key(
    $user_id,
    $key_id,
);

Sends a DELETE request to /users/:user_id/keys/:key_id.

SESSION METHODS

See http://doc.gitlab.com/ce/api/session.html.

session

$api->session(
    \%params,
);

Sends a POST request to /session.

PROJECT METHODS

See http://doc.gitlab.com/ce/api/projects.html.

projects

my $projects = $api->projects(
    \%params,
);

Sends a GET request to /projects and returns the decoded/deserialized response body.

owned_projects

my $projects = $api->owned_projects();

Sends a GET request to /projects/owned and returns the decoded/deserialized response body.

all_projects

my $projects = $api->all_projects();

Sends a GET request to /projects/all and returns the decoded/deserialized response body.

project

my $project = $api->project(
    $project_id,
);

Sends a GET request to /projects/:project_id and returns the decoded/deserialized response body.

project_events

my $events = $api->project_events(
    $project_id,
);

Sends a GET request to /projects/:project_id/events and returns the decoded/deserialized response body.

create_project

my $project = $api->create_project(
    \%params,
);

Sends a POST request to /projects and returns the decoded/deserialized response body.

create_project_for_user

$api->create_project_for_user(
    $user_id,
    \%params,
);

Sends a POST request to /projects/user/:user_id.

fork_project

$api->fork_project(
    $project_id,
);

Sends a POST request to /pojects/fork/:project_id.

delete_project

$api->delete_project(
    $project_id,
);

Sends a DELETE request to /projects/:project_id.

project_members

my $members = $api->project_members(
    $project_id,
);

Sends a GET request to /projects/:project_id/members and returns the decoded/deserialized response body.

project_member

my $member = $api->project_member(
    $project_id,
    $user_id,
);

Sends a GET request to /project/:project_id/members/:user_id and returns the decoded/deserialized response body.

add_project_member

$api->add_project_member(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/members.

edit_project_member

$api->edit_project_member(
    $project_id,
    $user_id,
    \%params,
);

Sends a PUT request to /projects/:project_id/members/:user_id.

remove_project_member

$api->remove_project_member(
    $project_id,
    $user_id,
);

Sends a DELETE request to /projects/:project_id/members/:user_id.

project_hooks

my $hooks = $api->project_hooks(
    $project_id,
);

Sends a GET request to /projects/:project_id/hooks and returns the decoded/deserialized response body.

project_hook

my $hook = $api->project_hook(
    $project_id,
    $hook_id,
);

Sends a GET request to /project/:project_id/hooks/:hook_id and returns the decoded/deserialized response body.

create_project_hook

$api->create_project_hook(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/hooks.

edit_project_hook

$api->edit_project_hook(
    $project_id,
    $hook_id,
    \%params,
);

Sends a PUT request to /projects/:project_id/hooks/:hook_id.

delete_project_hook

my $hook = $api->delete_project_hook(
    $project_id,
    $hook_id,
);

Sends a DELETE request to /projects/:project_id/hooks/:hook_id and returns the decoded/deserialized response body.

set_project_fork

$api->set_project_fork(
    $project_id,
    $forked_from_id,
);

Sends a POST request to /projects/:project_id/fork/:forked_from_id.

clear_project_fork

$api->clear_project_fork(
    $project_id,
);

Sends a DELETE request to /projects/:project_id/fork.

search_projects_by_name

my $projects = $api->search_projects_by_name(
    $query,
    \%params,
);

Sends a GET request to /projects/search/:query and returns the decoded/deserialized response body.

SNIPPET METHODS

See http://doc.gitlab.com/ce/api/project_snippets.html.

snippets

my $snippets = $api->snippets(
    $project_id,
);

Sends a GET request to /projects/:project_id/snippets and returns the decoded/deserialized response body.

snippet

my $snippet = $api->snippet(
    $project_id,
    $snippet_id,
);

Sends a GET request to /projects/:project_id/snippets/:snippet_id and returns the decoded/deserialized response body.

create_snippet

$api->create_snippet(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/snippets.

edit_snippet

$api->edit_snippet(
    $project_id,
    $snippet_id,
    \%params,
);

Sends a PUT request to /projects/:project_id/snippets/:snippet_id.

delete_snippet

$api->delete_snippet(
    $project_id,
    $snippet_id,
);

Sends a DELETE request to /projects/:project_id/snippets/:snippet_id.

raw_snippet

my $content = $api->raw_snippet(
    $project_id,
    $snippet_id,
);

Sends a GET request to /projects/:project_id/snippets/:snippet_id/raw and returns the decoded/deserialized response body.

REPOSITORY METHODS

See http://doc.gitlab.com/ce/api/repositories.html.

tags

my $tags = $api->tags(
    $project_id,
);

Sends a GET request to /projects/:project_id/repository/tags and returns the decoded/deserialized response body.

create_tag

$api->create_tag(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/repository/tags.

tree

my $tree = $api->tree(
    $project_id,
    \%params,
);

Sends a GET request to /projects/:project_id/repository/tree and returns the decoded/deserialized response body.

blob

my $blob = $api->blob(
    $project_id,
    $ref,
    \%params,
);

Sends a GET request to /projects/:project_id/repository/blobs/:ref and returns the decoded/deserialized response body.

raw_blob

my $raw_blob = $api->raw_blob(
    $project_id,
    $blob_sha,
);

Sends a GET request to /projects/:project_id/repository/raw_blobs/:blob_sha and returns the decoded/deserialized response body.

archive

my $archive = $api->archive(
    $project_id,
    \%params,
);

Sends a GET request to /projects/:project_id/repository/archive and returns the decoded/deserialized response body.

compare

my $comparison = $api->compare(
    $project_id,
    \%params,
);

Sends a GET request to /projects/:project_id/repository/compare and returns the decoded/deserialized response body.

contributors

my $contributors = $api->contributors(
    $project_id,
);

Sends a GET request to /projects/:project_id/repository/contributors and returns the decoded/deserialized response body.

FILE METHODS

See http://doc.gitlab.com/ce/api/repository_files.html.

file

my $file = $api->file(
    $project_id,
    \%params,
);

Sends a GET request to /projects/:project_id/repository/files and returns the decoded/deserialized response body.

create_file

$api->create_file(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/repository/files.

edit_file

$api->edit_file(
    $project_id,
    \%params,
);

Sends a PUT request to /projects/:project_id/repository/files.

delete_file

$api->delete_file(
    $project_id,
    \%params,
);

Sends a DELETE request to /projects/:project_id/repository/files.

COMMIT METHODS

See http://doc.gitlab.com/ce/api/commits.html.

commits

my $commits = $api->commits(
    $project_id,
    \%params,
);

Sends a GET request to /projects/:project_id/repository/commits and returns the decoded/deserialized response body.

commit

my $commit = $api->commit(
    $project_id,
    $commit_sha,
);

Sends a GET request to /projects/:project_id/repository/commits/:commit_sha and returns the decoded/deserialized response body.

commit_diff

my $diff = $api->commit_diff(
    $project_id,
    $commit_sha,
);

Sends a GET request to /projects/:project_id/repository/commits/:commit_sha/diff and returns the decoded/deserialized response body.

commit_comments

my $comments = $api->commit_comments(
    $project_id,
    $commit_sha,
);

Sends a GET request to /projects/:project_id/repository/commits/:commit_sha/comments and returns the decoded/deserialized response body.

add_commit_comment

$api->add_commit_comment(
    $project_id,
    $commit_sha,
    \%params,
);

Sends a POST request to /projects/:project_id/repository/commits/:commit_sha/comments.

BRANCH METHODS

See http://doc.gitlab.com/ce/api/branches.html.

branches

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

Sends a GET request to /projects/:project_id/repository/branches and returns the decoded/deserialized response body.

branch

my $branch = $api->branch(
    $project_id,
    $branch_name,
);

Sends a GET request to /projects/:project_id/repository/branches/:branch_name and returns the decoded/deserialized response body.

protect_branch

$api->protect_branch(
    $project_id,
    $branch_name,
);

Sends a PUT request to /projects/:project_id/repository/branches/:branch_name/protect.

unprotect_branch

$api->unprotect_branch(
    $project_id,
    $branch_name,
);

Sends a PUT request to /projects/:project_id/repository/branches/:branch_name/unprotect.

create_branch

my $branch = $api->create_branch(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/repository/branches and returns the decoded/deserialized response body.

delete_branch

$api->delete_branch(
    $project_id,
    $branch_name,
);

Sends a DELETE request to /projects/:project_id/repository/branches/:branch_name.

MERGE REQUEST METHODS

See http://doc.gitlab.com/ce/api/merge_requests.html.

merge_requests

my $merge_requests = $api->merge_requests(
    $project_id,
);

Sends a GET request to /projects/:project_id/merge_requests and returns the decoded/deserialized response body.

merge_request

my $merge_request = $api->merge_request(
    $project_id,
    $merge_request_id,
);

Sends a GET request to /projects/:project_id/merge_request/:merge_request_id and returns the decoded/deserialized response body.

create_merge_request

my $merge_request = $api->create_merge_request(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/merge_requests and returns the decoded/deserialized response body.

edit_merge_request

my $merge_request = $api->edit_merge_request(
    $project_id,
    $merge_request_id,
    \%params,
);

Sends a PUT request to /projects/:project_id/merge_requests/:merge_request_id and returns the decoded/deserialized response body.

accept_merge_request

$api->accept_merge_request(
    $project_id,
    $merge_request_id,
    \%params,
);

Sends a PUT request to /projects/:project_id/merge_requests/:merge_request_id/merge.

add_merge_request_comment

$api->add_merge_request_comment(
    $project_id,
    $merge_request_id,
    \%params,
);

Sends a POST request to /projects/:project_id/merge_requests/:merge_request_id/comments.

merge_request_comments

my $comments = $api->merge_request_comments(
    $project_id,
    $merge_request_id,
);

Sends a GET request to /projects/:project_id/merge_requests/:merge_request_id/comments and returns the decoded/deserialized response body.

ISSUE METHODS

See http://doc.gitlab.com/ce/api/issues.html.

all_issues

my $issues = $api->all_issues(
    \%params,
);

Sends a GET request to /issues and returns the decoded/deserialized response body.

issues

my $issues = $api->issues(
    $project_id,
    \%params,
);

Sends a GET request to /projects/:project_id/issues and returns the decoded/deserialized response body.

issue

my $issue = $api->issue(
    $project_id,
    $issue_id,
);

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

create_issue

my $issue = $api->create_issue(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/issues and returns the decoded/deserialized response body.

edit_issue

my $issue = $api->edit_issue(
    $project_id,
    $issue_id,
    \%params,
);

Sends a PUT request to /projects/:project_id/issues/:issue_id and returns the decoded/deserialized response body.

LABEL METHODS

See http://doc.gitlab.com/ce/api/labels.html.

labels

my $labels = $api->labels(
    $project_id,
);

Sends a GET request to /projects/:project_id/labels and returns the decoded/deserialized response body.

create_label

my $label = $api->create_label(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/labels and returns the decoded/deserialized response body.

delete_label

$api->delete_label(
    $project_id,
    \%params,
);

Sends a DELETE request to /projects/:project_id/labels.

edit_label

my $label = $api->edit_label(
    $project_id,
    \%params,
);

Sends a PUT request to /projects/:project_id/labels and returns the decoded/deserialized response body.

MILESTONE METHODS

See http://doc.gitlab.com/ce/api/milestones.html.

milestones

my $milestones = $api->milestones(
    $project_id,
);

Sends a GET request to /projects/:project_id/milestones and returns the decoded/deserialized response body.

milestone

my $milestone = $api->milestone(
    $project_id,
    $milestone_id,
);

Sends a GET request to /projects/:project_id/milestones/:milestone_id and returns the decoded/deserialized response body.

create_milestone

$api->create_milestone(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/milestones.

edit_milestone

$api->edit_milestone(
    $project_id,
    $milestone_id,
    \%params,
);

Sends a PUT request to /projects/:project_id/milestones/:milestone_id.

NOTE METHODS

See http://doc.gitlab.com/ce/api/notes.html.

notes

my $notes = $api->notes(
    $project_id,
    $note_type,
    $merge_request_id,
);

Sends a GET request to /projects/:project_id/:note_type/:merge_request_id/notes and returns the decoded/deserialized response body.

note

my $note = $api->note(
    $project_id,
    $note_type,
    $merge_request_id,
    $note_id,
);

Sends a GET request to /projects/:project_id/:note_type/:merge_request_id/notes/:note_id and returns the decoded/deserialized response body.

create_note

$api->create_note(
    $project_id,
    $note_type,
    $merge_request_id,
    \%params,
);

Sends a POST request to /projects/:project_id/:note_type/:merge_request_id/notes.

DEPLOY KEY METHODS

See http://doc.gitlab.com/ce/api/deploy_keys.html.

deploy_keys

my $keys = $api->deploy_keys(
    $project_id,
);

Sends a GET request to /projects/:project_id/keys and returns the decoded/deserialized response body.

deploy_key

my $key = $api->deploy_key(
    $project_id,
    $key_id,
);

Sends a GET request to /projects/:project_id/keys/:key_id and returns the decoded/deserialized response body.

create_deploy_key

$api->create_deploy_key(
    $project_id,
    \%params,
);

Sends a POST request to /projects/:project_id/keys.

delete_deploy_key

$api->delete_deploy_key(
    $project_id,
    $key_id,
);

Sends a DELETE request to /projects/:project_id/keys/:key_id.

SYSTEM HOOK METHODS

See http://doc.gitlab.com/ce/api/system_hooks.html.

hooks

my $hooks = $api->hooks();

Sends a GET request to /hooks and returns the decoded/deserialized response body.

create_hook

$api->create_hook(
    \%params,
);

Sends a POST request to /hooks.

test_hook

my $hook = $api->test_hook(
    $hook_id,
);

Sends a GET request to /hooks/:hook_id and returns the decoded/deserialized response body.

delete_hook

$api->delete_hook(
    $hook_id,
);

Sends a DELETE request to /hooks/:hook_id.

GROUP METHODS

See http://doc.gitlab.com/ce/api/groups.html.

groups

my $groups = $api->groups();

Sends a GET request to /groups and returns the decoded/deserialized response body.

group

my $group = $api->group(
    $group_id,
);

Sends a GET request to /groups/:group_id and returns the decoded/deserialized response body.

create_group

$api->create_group(
    \%params,
);

Sends a POST request to /groups.

transfer_project

$api->transfer_project(
    $group_id,
    $project_id,
);

Sends a POST request to /groups/:group_id/projects/:project_id.

delete_group

$api->delete_group(
    $group_id,
);

Sends a DELETE request to /groups/:group_id.

group_members

my $members = $api->group_members(
    $group_id,
);

Sends a GET request to /groups/:group_id/members and returns the decoded/deserialized response body.

add_group_member

$api->add_group_member(
    $group_id,
    \%params,
);

Sends a POST request to /groups/:group_id/members.

remove_group_member

$api->remove_group_member(
    $group_id,
    $user_id,
);

Sends a DELETE request to /groups/:group_id/members/:user_id.

SERVICE METHODS

See http://doc.gitlab.com/ce/api/services.html.

edit_project_service

$api->edit_project_service(
    $project_id,
    $service_name,
    \%params,
);

Sends a PUT request to /projects/:project_id/services/:service_name.

delete_project_service

$api->delete_project_service(
    $project_id,
    $service_name,
);

Sends a DELETE request to /projects/:project_id/services/:service_name.

SEE ALSO

Net::Gitlab purports to provide an interface to the GitLab API, but it is hard to tell due to a complete lack of documentation via either POD or unit tests.

CONTRIBUTING

This module is auto-generated from a set of YAML files defining the interface of GitLab's API. If you'd like to contribute to this module then please feel free to make a fork on GitHub and submit a pull request, just make sure you edit the files in the authors/ directory instead of lib/GitLab/API/v3.pm directly.

Please see https://github.com/bluefeet/GitLab-API-v3/blob/master/author/README.pod for more information.

Alternatively, you can open a ticket.

AUTHOR

Aran Clary Deltac <bluefeet@gmail.com>

CONTRIBUTORS

• dotandimet

ACKNOWLEDGEMENTS

Thanks to ZipRecruiter for encouraging their employees to contribute back to the open source ecosystem. Without their dedication to quality software development this distribution would not exist.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.