[pve-devel] API - GET /nodes/{node}/storage

[Fabian Grünbichler]

On Tue, Apr 17, 2018 at 02:47:01PM +0200, Andreas Steinel wrote:
> On Tue, Apr 17, 2018 at 2:09 PM, Fabian Grünbichler
> <f.gruenbichler at proxmox.com> wrote:
> > there are some places where we really don't know much more than "some
> > object" (because the API call does a bit too much, and can return one
> > thing or another depending on the code path taken), but in many cases,
> > extending the information should be straight-forward and improve the
> > generated API documentation a lot! so if you do check an API endpoint
> > for your use case and are fairly sure about the returned values, please
> > send a patch..
> 
> I'm totally unfamiliar with extjs and I thought this api (the big JSON thing)
> is generated somehow from the code itself as a kind of documentation or
> reference.

it is :) our API framework has a method to dump all the registered API
endpoints, and in our pve-docs repo we have a script that converts that
to json (pve-docs/extractapi.pl). similary, the man pages / synopsis /
help output / bash completion is generated mostly automatically from the
API schema / code. this has the big advantage of keeping the docs in
sync with the actual code without manual intervention (modulo any
manually added examples and long-form descriptions in pve-docs).

> I'm willing to fix things if I found not so well documented things.
> Can you point
> me to the file(s) and package(s) in question to change?

1.) extend the missing/incomplete return values in the API definitions
    in the perl code (e.g., pve-storage/PVE/API2/Storage/Status.pm)
2.) build and install the modified package containing the API (e.g.,
    pve-storage/libpve-storage-perl)
3.) regenerate the api-viewer files in pve-docs ("make update-static")
4.) build and install pve-docs package

you only need to send the patch from step 1, the rest will be done after
a few changes have been collected in the respective repositories, as
part of the regular package release cycles. so steps 2-4 are just to see
the changes in effect to verify they work as expected ;)

hope this helps. it might help to take a look at some of the better
annotated examples of return values, e.g. GET /cluster/config/join .

if something is unclear, don't hesitate to ask!