API Questions

[adamkrone]

Hello,

I'm currently working on an API client in Go as well as a Terraform provider, and I have a few questions regarding the API:

1. The API wiki mentions the use of JSON Schema, however I haven't been able to find any information on the schema files themselves. Are they publicly available anywhere? They would be immensely helpful, and might allow me to automatically generate some of the code in my client.
2. While the API documentation is useful in crafting requests, it doesn't really provide any useful information on the response. For example, GET /access/groups/{groupid} indicates that it returns an object, however there is no information as to what that object might contain. Is there a reason for this? Are only the request objects defined in the JSON schema?
3. I've noticed that many (perhaps all?) non-GET methods return null, which is unusual compared to many of the APIs I've worked with in the past. This becomes a problem when consuming some of the API resources, primarily those that have auto-generated ids (e.g. backups). If I'm managing containers or groups, for example, this isn't a problem as they both have user-defined ids (vmid, groupid). If I'm managing backups, however, the API controls the id, and it looks like the only way to retrieve the id from the API is by listing all backups. In general, I just don't see how I could reliably determine which resource is the one I just created, especially if it's possible for multiple resources to only differ by their ids. It would be a lot better if the non-GET methods could return the object (with the auto-generated id), just as it is returned when making a GET request. Is this something that could be added to the roadmap?

 

[dietmar]

• The API wiki mentions the use of JSON Schema, however I haven't been able to find any information on the schema files themselves. Are they publicly available anywhere? They would be immensely helpful, and might allow me to automatically generate some of the code in my client.

They ship with the pve-docs package, file "/usr/share/pve-docs/api-viewer/apidoc.js"

• While the API documentation is useful in crafting requests, it doesn't really provide any useful information on the response. For example, GET /access/groups/{groupid} indicates that it returns an object, however there is no information as to what that object might contain. Is there a reason for this? Are only the request objects defined in the JSON schema?

This is work in progress, but most calls miss that info.

• I've noticed that many (perhaps all?) non-GET methods return null, which is unusual compared to many of the APIs I've worked with in the past. This becomes a problem when consuming some of the API resources, primarily those that have auto-generated ids (e.g. backups). If I'm managing containers or groups, for example, this isn't a problem as they both have user-defined ids (vmid, groupid). If I'm managing backups, however, the API controls the id, and it looks like the only way to retrieve the id from the API is by listing all backups. In general, I just don't see how I could reliably determine which resource is the one I just created, especially if it's possible for multiple resources to only differ by their ids. It would be a lot better if the non-GET methods could return the object (with the auto-generated id), just as it is returned when making a GET request. Is this something that could be added to the roadmap?

Please join the pve-devel list if you want to change something specific.

 

[adamkrone]

Thanks for the info, I'll follow up on the pve-devel list.