[pve-devel] [PATCH pve-manager v3 0/2] api: add return schemas

[pve-devel] [PATCH pve-manager v3 0/2] api: add return schemas

[Nicolas Frey]

Changes since v2, thanks to @Thomas Lamprecht:
* clone $apt_package_return_props rather than modifying hash ref
* touch up on replication api return props by adding guest, jobnum
  and digest properties

Nicolas Frey (2):
  api: add APT versions return schema
  api: add replication config read return schema

 PVE/API2/APT.pm               | 114 ++++++++++++++++++++--------------
 PVE/API2/ReplicationConfig.pm |  22 ++++++-
 2 files changed, 88 insertions(+), 48 deletions(-)

-- 
2.47.3


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH pve-manager v3 1/2] api: add APT versions return schema

[Nicolas Frey]

The Arch property now includes all officially supported debian
Architectures [0]. These could be extended to include unofficial
ones as well, though I don't see a reason to currently do this.
The CurrentState property now includes all variants according to
the documentation of package AptPkg::Cache.

Also implemented suggestion to clone $apt_package_return_props
instead of modifying, which could've potentially resulted in
unwanted behaviour.

[0] https://wiki.debian.org/SupportedArchitectures

Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
---
 PVE/API2/APT.pm | 114 +++++++++++++++++++++++++++++-------------------
 1 file changed, 68 insertions(+), 46 deletions(-)

diff --git a/PVE/API2/APT.pm b/PVE/API2/APT.pm
index 0d07cf38..fdc9f622 100644
--- a/PVE/API2/APT.pm
+++ b/PVE/API2/APT.pm
@@ -200,6 +200,52 @@ my $update_pve_pkgstatus = sub {
     return $pkglist;
 };
 
+my $apt_package_return_props = {
+    Arch => {
+        type => 'string',
+        description => 'Package Architecture.',
+        enum => [qw(armhf arm64 amd64 ppc64el risc64 s390x)],
+    },
+    Description => {
+        type => 'string',
+        description => 'Package description.',
+    },
+    NotifyStatus => {
+        type => 'string',
+        description => 'Version for which PVE has already sent an update notification for.',
+        optional => 1,
+    },
+    OldVersion => {
+        type => 'string',
+        description => 'Old version currently installed.',
+        optional => 1,
+    },
+    Origin => {
+        type => 'string',
+        description => "Package origin, e.g., 'Proxmox' or 'Debian'.",
+    },
+    Package => {
+        type => 'string',
+        description => 'Package name.',
+    },
+    Priority => {
+        type => 'string',
+        description => 'Package priority.',
+    },
+    Section => {
+        type => 'string',
+        description => 'Package section.',
+    },
+    Title => {
+        type => 'string',
+        description => 'Package title.',
+    },
+    Version => {
+        type => 'string',
+        description => 'New version to be updated to.',
+    },
+};
+
 __PACKAGE__->register_method({
     name => 'list_updates',
     path => 'update',
@@ -220,51 +266,7 @@ __PACKAGE__->register_method({
         type => "array",
         items => {
             type => "object",
-            properties => {
-                'Arch' => {
-                    type => 'string',
-                    description => 'Package Architecture.',
-                },
-                'Description' => {
-                    type => 'string',
-                    description => 'Human-readable package description.',
-                },
-                'NotifyStatus' => {
-                    type => 'string',
-                    description =>
-                        'Version for which PVE has already sent an update notification for.',
-                    optional => 1,
-                },
-                'OldVersion' => {
-                    type => 'string',
-                    description => 'Old version currently installed.',
-                    optional => 1,
-                },
-                'Origin' => {
-                    type => 'string',
-                    description => 'Package origin.',
-                },
-                'Package' => {
-                    type => 'string',
-                    description => 'Package name.',
-                },
-                'Priority' => {
-                    type => 'string',
-                    description => 'Package priority in human-readable form.',
-                },
-                'Section' => {
-                    type => 'string',
-                    description => 'Package section.',
-                },
-                'Title' => {
-                    type => 'string',
-                    description => 'Package title.',
-                },
-                'Version' => {
-                    type => 'string',
-                    description => 'New version to be updated to.',
-                },
-            },
+            properties => $apt_package_return_props,
         },
     },
     code => sub {
@@ -788,7 +790,27 @@ __PACKAGE__->register_method({
         type => "array",
         items => {
             type => "object",
-            properties => {},
+                properties => {
+                    $apt_package_return_props->%*,
+                    CurrentState => {
+                        type => 'string',
+                        description => 'Current state of the package installed on the system.',
+                        # Possible CurrentState variants according to AptPkg::Cache
+                        enum => [
+                        qw(Installed NotInstalled UnPacked HalfConfigured HalfInstalled ConfigFiles)
+                        ],
+                    },
+                    RunningKernel => {
+                        type => 'string',
+                        description => "Kernel release, only for package 'proxmox-ve'.",
+                        optional => 1,
+                    },
+                    ManagerVersion => {
+                        type => 'string',
+                        description => "Version of the currently running pve-manager API server.",
+                        optional => 1,
+                    },
+                }
         },
     },
     code => sub {
-- 
2.47.3


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH pve-manager v3 2/2] api: add replication config read return schema

[Nicolas Frey]

The return props now include programmatically added properties guest,
jobnum, and digest (the latter only being returned in read endpoint)
in addition to the create schema.

Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
---
 PVE/API2/ReplicationConfig.pm | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/PVE/API2/ReplicationConfig.pm b/PVE/API2/ReplicationConfig.pm
index 307ebe69..d62caa2a 100644
--- a/PVE/API2/ReplicationConfig.pm
+++ b/PVE/API2/ReplicationConfig.pm
@@ -17,6 +17,18 @@ use PVE::API2::Replication;
 
 use base qw(PVE::RESTHandler);
 
+my $replication_api_return_props = {
+    PVE::ReplicationConfig->createSchema()->{properties}->%*,
+    guest => {
+        type => 'integer',
+        description => 'Guest ID.',
+    },
+    jobnum => {
+        type => 'integer',
+        description => 'Unique, sequential ID assigned to each job.',
+    },
+};
+
 __PACKAGE__->register_method({
     name => 'index',
     path => '',
@@ -35,7 +47,7 @@ __PACKAGE__->register_method({
         type => 'array',
         items => {
             type => "object",
-            properties => {},
+            properties => $replication_api_return_props,
         },
         links => [{ rel => 'child', href => "{id}" }],
     },
@@ -75,7 +87,13 @@ __PACKAGE__->register_method({
             id => get_standard_option('pve-replication-id'),
         },
     },
-    returns => { type => 'object' },
+    returns => {
+        type => "object",
+        properties => {
+            $replication_api_return_props->%*,
+            digest => get_standard_option('pve-config-digest'),
+        },
+    },
     code => sub {
         my ($param) = @_;
 
-- 
2.47.3


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] applied: [PATCH pve-manager v3 0/2] api: add return schemas

[Thomas Lamprecht]

On Thu, 02 Oct 2025 14:47:26 +0200, Nicolas Frey wrote:
> Changes since v2, thanks to @Thomas Lamprecht:
> * clone $apt_package_return_props rather than modifying hash ref
> * touch up on replication api return props by adding guest, jobnum
>   and digest properties
> 
> Nicolas Frey (2):
>   api: add APT versions return schema
>   api: add replication config read return schema
> 
> [...]

Applied, thanks!

[1/2] api: add APT versions return schema
      commit: 6deba095c5f0aa4b4673d89be53a9d461b908f16
[2/2] api: add replication config read return schema
      commit: 65a80884b038a819334c8a1d988afd64b1b9fb89


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel