[pve-devel] Json reply format

[Fabian Grünbichler]

On Wed, Mar 21, 2018 at 05:36:00PM +0300, Maxim Voronov wrote:
> 
> 
> 21.03.2018 17:17, Thomas Lamprecht wrote:
> > Hi,
> > 
> > On 3/21/18 2:46 PM, Maxim Voronov wrote:
> > > Hello again,
> > > 
> > > I'm working on PVE rest api client and using this documentation: https://pve.proxmox.com/pve-docs/api-viewer/index.html
> > > 
> > > According to this documentation calling GET /api2/json/access/domains will return me an array,
> > > 
> > > but I did not found description of what objects are in the array. To get the format of objects I call endpoints of our production PVE server :-D
> > > 
> > > The question is - where can I have a look at json reply formats for all of endpoint ?
> > > 
> > There are two problems for easy viewing this info
> > through the API viewer.
> > 
> > 1) we only show the top level type
> > 
> > 2) Unfortunately we have not all return types fully annotated.
> > With new API call we try to be more thorough with that, but
> > for older ones you may often not come around of reading the
> > code or simply testing it by doing the call, I'm afraid.
> > 
> > E.g., for the domains and other /access related stuff you can
> > find the API code in the pve-access-control git repository,
> > a web view for the domain API call would be:
> > 
> > https://git.proxmox.com/?p=pve-access-control.git;a=blob;f=PVE/API2/Domains.pm;h=b5fa65efc9253847ee49e73bef577c0ab9cf2bf9;hb=HEAD#l52
> > 
> > (this one is already annotated about what it returns)
> > 
> > Ideally we would find time to annotate all the API calls but
> > as this needs quite a bit of time and does not brings an effect
> > for 99% of our users its on the back burner.
> > 
> > 
> > I can look into showing at least the info we already have in the
> > API viewer, makes sense to me.
> > 
> > cheers,
> > Thomas
> > 
> 
> I understand the problem. Hope the API code will help me not to miss
> something.

if you see places where the return type is missing but obvious/simple,
feel free to send patches[1]! there are some cases were the return type
is some kind of nested hash with arrays, in which case it might not be
easily described with JSONSchema syntax, or some special cases where the
return type is very different depending on code paths taken..

@all

maybe it would make sense to add a description field for the return type
like we have for the permissions? then the API viewer could display
something meaningful even in cases where we can't press the return type
into a strict specification for whatever reasons?

unfortunately the 'return' property is not extendable without lots of
code churn and client breakage, so we'd need an extra
'return_description' property or something like that (or we postpone it
to the next major API bump and refactor the 'return' property to have
description and specification sub-properties).

1: https://pve.proxmox.com/wiki/Developer_Documentation