[pmg-devel] [PATCH pmg-api] API: Mailtracker: add values to rstatus and dstatus description

[pmg-devel] [PATCH pmg-api] API: Mailtracker: add values to rstatus and dstatus description

[Aaron Lauterer]

The possible values were only documented within the source code. Having
them as part of the API description will help people wanting to use the
tracker API endpoint interpreting the results.

Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
---
 src/PMG/API2/MailTracker.pm | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/src/PMG/API2/MailTracker.pm b/src/PMG/API2/MailTracker.pm
index 187decf..952abc8 100644
--- a/src/PMG/API2/MailTracker.pm
+++ b/src/PMG/API2/MailTracker.pm
@@ -38,6 +38,14 @@ my $statmap = {
     Q => 'quarantine',
 };
 
+my $print_statmap = sub {
+    my $map = "";
+    foreach my $key (sort keys %$statmap) {
+	$map .= "$key: $statmap->{$key}\n";
+    }
+    return $map;
+};
+
 my $run_pmg_log_tracker = sub {
     my ($args, $includelog) = @_;
 
@@ -247,13 +255,15 @@ my $email_log_property_desc = {
 	type => 'integer',
     },
     dstatus => {
-	description => "Delivery status.",
+	description => "Delivery status. Can be one of the following values:\n" .
+	$print_statmap->(),
 	type => 'string',
 	minLength => 1,
 	maxLength => 1,
     },
     rstatus => {
-	description => "Delivery status of relayed mail.",
+	description => "Delivery status of relayed mail. Can be one of the " .
+	"following values:\n" . $print_statmap->(),
 	type => 'string',
 	minLength => 1,
 	maxLength => 1,
-- 
2.30.2

Re: [pmg-devel] [PATCH pmg-api] API: Mailtracker: add values to rstatus and dstatus description

[Mira Limbeck]

some comments inline

On 8/12/21 5:30 PM, Aaron Lauterer wrote:
> The possible values were only documented within the source code. Having
> them as part of the API description will help people wanting to use the
> tracker API endpoint interpreting the results.
>
> Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>
> ---
>   src/PMG/API2/MailTracker.pm | 14 ++++++++++++--
>   1 file changed, 12 insertions(+), 2 deletions(-)
>
> diff --git a/src/PMG/API2/MailTracker.pm b/src/PMG/API2/MailTracker.pm
> index 187decf..952abc8 100644
> --- a/src/PMG/API2/MailTracker.pm
> +++ b/src/PMG/API2/MailTracker.pm
> @@ -38,6 +38,14 @@ my $statmap = {
>       Q => 'quarantine',
>   };
>   
> +my $print_statmap = sub {
> +    my $map = "";
> +    foreach my $key (sort keys %$statmap) {
> +	$map .= "$key: $statmap->{$key}\n";
> +    }
> +    return $map;
> +};
> +
>   my $run_pmg_log_tracker = sub {
>       my ($args, $includelog) = @_;
>   
> @@ -247,13 +255,15 @@ my $email_log_property_desc = {
>   	type => 'integer',
>       },
>       dstatus => {
> -	description => "Delivery status.",
> +	description => "Delivery status. Can be one of the following values:\n" .
> +	$print_statmap->(),

Maybe, instead of adding it to the description, change the type from 
`string` to `enum` with the few possible values.

This should result in a nice overview of the possible return values in 
the API viewer.

>   	type => 'string',
>   	minLength => 1,
>   	maxLength => 1,
>       },
>       rstatus => {
> -	description => "Delivery status of relayed mail.",
> +	description => "Delivery status of relayed mail. Can be one of the " .
> +	"following values:\n" . $print_statmap->(),
Same here, as only `2`, `4` and `5` are valid `rstatus` values.
>   	type => 'string',
>   	minLength => 1,
>   	maxLength => 1,