Relationship traversal

The relationships defined within the API model enable you to perform bulk operations on cloud objects and to reference deeply nested cloud objects with ease. The process of using relationships to navigate within your cloud structure is called relationship traversal.

API-patterns that involve relationships enable you to specify one relationship or a sequence of relationships. When a sequence of two or more relationships is specified in an API request, the software steps through each named relationship in turn until it reaches the end of the sequence.

Depending on the API pattern of the request, one of these actions will be performed:

• Return the current value of the objects found at the end of the sequence.
• Perform the specified operation on the objects found at the end of the sequence.

You can use the following API patterns to specify relationships between cloud objects:

Because relationships can be chained together in a multitude of ways, only APIs that use a single relationship appear in the API-reference section. However, you are not limited to using only the APIs that appear there. You can use the API relationship patterns listed above to build custom API requests to navigate within your cloud structure.

The following examples show some API requests that you might create by using relationship-based API patterns.

Example: Retrieve the container blueprint for a specific network container

The following request retrieves the container blueprint associated with the network container specified by <guid>.

This example uses one relationship, containerBlueprint, which is a relationship of the NetworkContainer class.

Example: Find the zones in the network containers within a specific static pool

The following request returns a list of all zones that are in each of the network containers associated with the static pool identified by <guid>.

This example uses a sequence of two relationships: forNetworkContainer is a relationship of the StaticPool class and zones is a relationship of the NetworkContainer class. To process this request, the software finds the network containers associated with the static pool specified by <guid>, and then finds the zones in each of those network containers. The JSON document returned in response to this request contains a list of the network containers found for the static pool and a list of the zones in each of the network containers.

Example: Offboard virtual hosts within a specific virtual cluster

The following request offboards all virtual hosts associated with the virtual cluster identified by <guid>.

This example uses one relationship, virtualHosts, which is a relationship of the VirtualCluster class, and specifies offboard, an operation of the VirtualHost class, to be performed on the virtual hosts that are in the virtual cluster.