Relationship traversal

This topic contains the following sections:

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:

For relationship APIs, the API reference section lists only APIs that use a single relationship. However, relationships can be chained together in a multitude of ways — you are not limited to using only the APIs that appear in the API reference. You can use the API relationship patterns 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.

Using fillFields to restrict the returned attributes

To have tighter control over the specific attributes returned for each related object, you can use dot notation when specifying the fillFields arguments. Instead of entering just the relationship, enter relationship.attribute to specify the particular relationship AND attribute. For example, to retrieve the name of the associated resourceSet, enter resourceSet.name as the fillFields argument. For each related object returned in the results, certain attributes (such as cloudClass and guid are always included in the response regardless of the request arguments. From a performance perspective this may be advantageous due to the smaller size of the result. The following examples show the difference in the returned data depending on the form of the request.

Example: fillFields in the form <relationship>

Request

GET csm/Organization/OI-5B01B256C64B11E199EA0050569626B4/computeResource?fillFields=resourceSet

Response

{
  "cloudClass":"com.bmc.cloud.model.beans.ComputeContainer",
  "guid":"557cad15-708e-44bd-b5b5-0a2a66068205",
  "resourceSet":"/resourceset/c59e72de-3c16-4ce0-9bf0-7f8b9af64b97",
  "resourceSetObject":{
    "cloudClass":"com.bmc.cloud.model.beans.ResourceSet",
    "compute":[
      "/computecontainer/557cad15-708e-44bd-b5b5-0a2a66068205"
    ],
    "functionalComponents":[
      "/functionalcomponent/46c94942-f444-443e-8de2-cdea293ba06a"
    ],
    "guid":"c59e72de-3c16-4ce0-9bf0-7f8b9af64b97",
    "name":"IAAScentos5.5 64_rs",
    "networkContainer":"/networkcontainer/58a33ee1-3d1b-4f71-bad8-2c1f86d83483",
    "owner":"portaladmin",
    "reconciliationID":"OI-eb7cdccb1e044924911896aab5083107",
    "software":[
      "/softwareresource/3869f721-4bc4-47ab-8f2c-c1e88a860022",
      "/softwareresource/8bcab22e-2282-49c3-bce6-668ff7b8f34e",
      "/softwareresource/a69350de-6427-45c6-88f4-40e35d4721f6",
      "/softwareresource/a7ff4792-9f9a-4b2d-835c-384f7b8a33b9",
      "/softwareresource/f2623bbf-e27e-4337-8c1a-590ff9990bae"
    ],
    "state":"Running",
    "tenant":"/organization/OI-5B01B256C64B11E199EA0050569626B4",
    "tokenID":"78823a93-4ddb-4f09-af75-f9db13ebd830_c59e72de-3c16-4ce0-9bf0-7f8b9af64b97"
  }

Example: fillFields in the form <relationship>.<attribute>

Request

GET csm/Organization/OI-5B01B256C64B11E199EA0050569626B4/computeResource?fillFields=resourceSet.name

Response

{
   "cloudClass":"com.bmc.cloud.model.beans.ComputeContainer",
   "guid":"557cad15-708e-44bd-b5b5-0a2a66068205",
   "resourceSet":"/resourceset/c59e72de-3c16-4ce0-9bf0-7f8b9af64b97",
   "resourceSetObject":{
      "cloudClass":"com.bmc.cloud.model.beans.ResourceSet",
      "guid":"c59e72de-3c16-4ce0-9bf0-7f8b9af64b97",
      "name":"IAAScentos5.5 64_rs"
   }
}

Additional examples

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.