Sends a request constructed from the given `$template` and `$arguments` hashref.
Arguments that start with `-` (minus) are reserved to modify the client's behaviour and are **never** forwarded to GitLab.
...
...
@@ -136,23 +160,27 @@ The following methods are intended to be called from additional methods implemen
Returns data received from GitLab API, either as hashref or arrayref (this depends on the request) or `undef` if the request failed (and `die_on_error` is disabled).
Additionally it saves the last [HTTP::Response](https://metacpan.org/pod/HTTP::Response) object as the `response` attribute of `$self`.
The following arguments can be used to modify ["exec\_request"](#exec_request)'s behaviour:
The following arguments can be used to modify [`exec_request`](#exec_request)'s behaviour:
- `-response => [0|1]`
Return both data and the [HTTP::Response](https://metacpan.org/pod/HTTP::Response) object as a list of two elements if set to true value.
my ($data, $response) = $gitlab->$method(..., -response => 1);
```{.pl}
my ($data, $response) = $gitlab->$method(..., -response => 1);
```
- `-immortal => [0|1]`
When enabled, calls will not not carp on error even when `die_on_error` is enabled.
Recommended with `-response` option so that the status code can be inspected directly.
@@ -164,14 +192,18 @@ The following methods are intended to be called from additional methods implemen
# Package methods
- methods()
-`methods()`
$methods = GitLab::API::methods();
```{.pl}
$methods = GitLab::API::methods();
```
Returns an arrayref of method names registered with the API.
This method cannot be exported, use
This method __cannot__ be exported, use
GitLab::API::methods()
```{.pl}
GitLab::API::methods()
```
to obtain the result.
...
...
@@ -179,41 +211,46 @@ The following methods are intended to be called from additional methods implemen
Request methods are methods that create requests and call GitLab API.
This package provides an easy data-driven way to create such methods with
request templates (see ["REQUEST TEMPLATES"](#request-templates) section and ["register"](#register)
request templates (see ["REQUEST TEMPLATES"](#request-templates) section and [`register`](#register)
method below).
Unless specified otherwise, these methods take a hash of options, e.g.
$gitlab->$method(key => value, ...);
```{.pl}
$gitlab->$method(key => value, ...);
```
Generally, keys starting with the `-` (minus) characters are intended to modify the underlying `/exec_request`'s behaviour and are not forwarded to GitLab.
Generally, keys starting with the `-` (minus) characters are intended to modify the underlying `exec_request`'s behaviour and are not forwarded to GitLab.
This module contains only the ["whoami"](#whoami) API method, other methods are provided
This module contains only the [`whoami`](#whoami) API method, other methods are provided
by additional `GitLab::*` modules.
# REQUEST TEMPLATES
This section contains instruction on how to implement API request methods.
See [GitLab::Users](https://metacpan.org/pod/GitLab::Users) and [GitLab::Groups](https://metacpan.org/pod/GitLab::Groups) for examples.
See [`GitLab::Users`](pod-GitLab-Users.md) and [`GitLab::Groups`](pod-GitLab-Groups.md) for examples.
The requests are made by calling the ["exec\_request"](#exec_request) method with the following parameters:
The requests are made by calling the [`exec_request`](#exec_request) method with the following parameters:
| `method` | **[required]**`GET`, `POST`, `PUT` or `DELETE` |
| `path` | **[required]** URL relative to the URL parameter given to constructor |
| `paginated` | if set to `true`, the request will be repeated and results concatented until all items are obtained` |
| `query` | arrayref of paramters that should be passed as query string in the URL |
| `required` | arrayref of required arguments |
| `optional` | optional arguments |
| `ret` | hashref of HTTP codes whose values will be used as status messages |
The `path` value can contain placeholders in the format `<name>`, e.g. `/groups/<gid>/projects/<projid>` is a path that contains placeholders `gid` and `projid`.
When processing the template, these placeholders will automatically become _required arguments_.
When processing the template, these placeholders will automatically become __required arguments__.
Arguments specified in the `query` are _not_ required by default, hence, if missing, they will not be included in the final URL.
...
...
@@ -222,22 +259,26 @@ Additional arguments (those not mentioned in `query`) will be passed as the requ
Optional arguments can be specified by the `optional` key.
The value of this key is an arrayref with strings.
As the name suggests, _required arguments_ must be provided, otherwise the ["exec\_request"](#exec_request) will croak.
As the name suggests, _required arguments_ must be provided, otherwise the [`exec_request`](#exec_request) will croak.
## Examples
Consider the following template hashref:
my $user_by_id = {
name => "user_by_id",
method => "GET",
path => "/users/<uid>",
ret => { 404 => "User not found" },
};
```{.pl}
my $user_by_id = {
name => "user_by_id",
method => "GET",
path => "/users/<uid>",
ret => { 404 => "User not found" },
};
```
Called as `$gitlab->exec_request($user_by_id, { uid => 10 })`, the method will replace `<uid>` placeholder with `10` and then it will call
GET .../api/v3/users/10
```
GET .../api/v3/users/10
```
with empty content.
The `uid` argument is required; the method will croak if it is not present.
...
...
@@ -247,58 +288,69 @@ For other status codes it will return the reason provided either by GitLab or un
Another example:
my $user_add_ssh_key = {
name => "user_add_ssh_key",
method => "POST",
path => "/users/<uid>/keys",
required => [ qw!title key! ],
};
```{.pl}
my $user_add_ssh_key = {
name => "user_add_ssh_key",
method => "POST",
path => "/users/<uid>/keys",
required => [ qw!title key! ],
};
```
This request requires arguments `title`, `key` and `uid` (since it appears in the `path`).
The latter argument will be substituted in the path, the former two will be passed in the body of the request.
The third example uses pagination:
my $groups = {
name => "groups",
method => "GET",
path => "/groups",
query => [ qw!search! ],
paginated => 1,
};
```{.pl}
my $groups = {
name => "groups",
method => "GET",
path => "/groups",
query => [ qw!search! ],
paginated => 1,
};
```
When called, the request will be repeated with increasing `page` query value until all pages are returned.
These responses will be concatenated to a single one.
The method will croak if any of the returned pages is not an array.
In addition, the request _can_ have (but does not require) an argument `search` that will be passed in the query string (`...?search=$search`).
In addition, the request __can__ have (but does not require) an argument `search` that will be passed in the query string (`...?search=$search`).
In order to make this argument required, the template would have to contain the following key:
required => [ qw!search! ],
```{.pl}
# ...
required => [ qw!search! ],
```
as well.
## Registering methods
- register()
- `register()`
GitLab::API->register($template, ...);
```{.pl}
GitLab::API->register($template, ...);
```
Instead of modifying [GitLab::API](https://metacpan.org/pod/GitLab::API) source to add a new method, or writing wrapper subs like this:
Instead of modifying `GitLab::API` source to add a new method, or writing wrapper subs like this:
