vSphere & SOAP - API from Hell

[tbeboreus]

We are trying to use the vSphere SOAP API to gather some statistics and informations about running systems. During our development we have found so many stupid, useless, and irritating things,

that i thought to collect them here and "warn" other developers. Maybe some other could avoid making the same mistakes we did.

Generating Client Library

vSphere WSDL files and gSoap

Don't do it. It would work, but you will get trouble to compile it. The resulting files are so huge, we was not able to compile the library in less then 4 hours, without any optimization. And the resulting binary was >50MB.

Compiling with optimization flags? No way, unless you have systems with more den 128GB of RAM

axis2c

Not tested, as it first starting to complain about a missing service definition, because there is none in the WSDL file, even if they where fetched from the vSphere Server. After fixing that, the resltung files was even larger then from gSoap, so we deleted it and decided to not use any automatic generator for the C library.

Documentation Issues

The documentation is a mess. Exactly as the API definitions as a whole. So they match together, but readable is something else.

And there are some very confusing parts in the docs. For example:

The ServiceContent has an optional member: sessionManager. To retrieve these member, if it is not delivered by the api (as it is optional), we have to use the PropertyCollector. To create the matching filter we need the permission System.View -  but wait! How should we get a session with the according permission if we could not get the sessionManager  (to understand recursion you have to understand recursion first)? So we assume that the sessionManager is NOT optional.

So, if you have found the information you are looking for, and thought you understand what the author wanted to say: Think twice about it, sleep a night, think again and try to put some more logic in it. Don't trust the docs!

Broken API Design

If you use the API, you should always remember: It is broken by Design.

It starts with the request headers you have to use. ALL operations have the SOAP-Action  "urn:vim25/5.1" according to the vim.wsdl. Some operations need it, for other the header is ignored. I think somebody should explain the developers of the API what the header is really for: Maybe O'Reilly Unraveling the Mystery of SOAPAction - O'Reilly XML Blog ?

Also, all operations a tied to a specific type of Managed Object. In the documentation only of course! All defined operations requires the base type, Managed Object, to be set. There are no derived objects for the real types! That makes it very hard to understand the WSDL without the external documentation. Also, you may miss some errors in your code, if you assign the wrong object as _this to a operation.

TL;DR

The API is a piece of crap. Don't use it unless you really have to.