@@ -248,6 +248,7 @@ The _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 `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__.
...
...
@@ -261,8 +262,14 @@ 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.
All values for `path` placeholders are encoded before replacement.
However, if the value can contain reserved URI characters (e.g. `'/'`), the encoding must be forced.
This can be done by specifying this placeholder in the `encode` arrayref.
## Examples
### Simple
Consider the following template hashref:
```{.pl}
...
...
@@ -286,7 +293,7 @@ The `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 `404` with reason `User not found`.
For other status codes it will return the reason provided either by GitLab or underlying HTTP client.
Another example:
### Required arguments
```{.pl}
my $user_add_ssh_key = {
...
...
@@ -300,7 +307,30 @@ my $user_add_ssh_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:
### Encoding
```{.pl}
my $project_by_id = {
method => "GET",
path => "/projects/<id>",
encode => [ qw(id) ],
};
```
From API documentation, this operation returns a project with the given `id`, which can be a numerical value or a string `"NAMESPACE/PROJECT_NAME"`.
Without the `encode` parameter in the template, the following request
```{.pl}
$gitlab->project_by_id("user/project");
```
would result in the path `gitlab_url/projects/user/project` which is invalid.
The slash, as a reserved character, needs to be encoded using `encode_required` parameter for [`URI::Encode`](https://metacpan.org/pod/URI::Encode).
This option is enabled by specifying `id` in the `encode` parameter in the template.
Final URL in this case would be `gitlab_url/projects/user%2Fproject`.
