@@ -588,6 +599,7 @@ The I<request template> is a hashref with the following keys:
required arrayref of required arguments
optional optional arguments
ret hashref of HTTP codes whose values will be used as status messages
encode arrayref of path components that should be URI-encoded
The C<path> value can contain placeholders in the format C<< <name> >>, e.g. C<< /groups/<gid>/projects/<projid> >> is a path that contains placeholders C<gid> and C<projid>.
When processing the template, these placeholders will automatically become I<required arguments>.
...
...
@@ -601,8 +613,14 @@ The value of this key is an arrayref with strings.
As the name suggests, I<required arguments> must be provided, otherwise the L</exec_request> will croak.
All values for C<path> placeholders are encoded before replacement.
However, if the value can contain reserved URI characters (e.g. C</>), the encoding must be forced.
This can be done by specifying this placeholder in the C<encode> arrayref.
=head2 Examples
=head3 Simple
Consider the following template hashref:
my $user_by_id = {
...
...
@@ -622,7 +640,7 @@ The C<uid> argument is required; the method will croak if it is not present.
If the given user is not found, the method will return status C<404> with reason C<User not found>.
For other status codes it will return the reason provided either by GitLab or underlying HTTP client.
Another example:
=head3 Required arguments
my $user_add_ssh_key = {
name => "user_add_ssh_key",
...
...
@@ -634,7 +652,26 @@ Another example:
This request requires arguments C<title>, C<key> and C<uid> (since it appears in the C<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:
=head3 Encoding
my $project_by_id = {
method => "GET",
path => "/projects/<id>",
encode => [ qw(id) ],
};
From API documentation, this operation returns a project with the given C<id>, which can be a numerical value or a string C<"NAMESPACE/PROJECT_NAME">.
Without the C<encode> parameter in the template, the following request
$gitlab->project_by_id("user/project");
would result in the path C<gitlab_url/projects/user/project> which is invalid.
The slash, as a reserved character, needs to be encoded using C<encode_required> parameter for L<URI::Encode>.
This option is enabled by specifying C<id> in the C<encode> parameter in the template.
Final URL in this case would be C<gitlab_url/projects/user%2Fproject>.