The functionality in the API follows a number of conventions. When reading the documentation, watch for the following conventions.

  • For CRUD functions (create, read, update, delete), the functions start with either create, get, update, or delete respectively.

  • Functions starting with build provide factory methods for creating complex objects. These are not persisted, but are offered as a helper service to the client code.

  • Data structures end with Info. These represent the domain objects in the system.

  • Functions that do not follow the above conventions are either providing association between domain objects, or executing some business logic.

  • ResourceIdentityInfo is the identity object, which contains the unique identifier in the attributed key. This is the object identifier or primary key unique to every object in the system.

The architecture of the API is such that the Web Services interface uses the J2EE interface in the background. The VMware Smart Assurance Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide is a document generated from the J2EE interface, causing some discrepancies between the document and the code generated from Web Services tools, such as Apache Axis.

That is because the Web Services Interface Definition (WSDL) is a translation. All the functions and parameters are the same in the J2EE version and the WSDL version, but the data structures of the parameters may differ slightly.

Note:

The WSDL is the interface definition for the web services interface, the javadoc serves to document the functions.

If you are using the Web Services interface, you need to be using the WSDL as the precise definition for each function. The VMware Smart Assurances Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide is still a good reference document if you are using Web Services, but there are some differences between what you see in the guide and the actual implementation of the code.

  • Collections in the guide are Arrays in Web Services implementations.

  • In some situations, the order of parameters can change between the WSDL and J2EE interface. The most notable example is with ResourceIdentityInfo. Keep this in mind when programming, and check the generated objects (if applicable) if you suspect this.

  • The java Date type is translated into a Calendar type for the WSDL interface.

Finally, a note about LDAP-style name lookups. In the documentation, the name lookup capability is detailed. Unfortunately, this is expensive. Some of the name lookups have been removed for performance reasons.

As a best practice, these lookup-style calls should only be used as an entry point to the API, before any internal Ids (OIDs or keys in the Resource Identity Info objects) have been obtained. Once the programmer has an entry point into the system, OIDs should always be used for API calls.

For best practices, keep in mind the load being put on the Network Configuration Manager system. Remember that a program can interact much faster with the application than users can. High volume traffic through the API can simulate many concurrent users of the system.

Note:

Note the following when making decisions concerning multi-threading a client program:

  • Technically, this is entirely possible, but is it a good thing to do from a system perspective?

  • You might also consider running high volume operations against the API when there are a minimum of users on the system.