Embedding subcollections - BlueCat Integrity - 9.5.0

Most resources have subcollections. For example, Zone resources have a resourceRecords subcollection containing all resource records in that Zone. To reduce the number of API calls when fetching resources and their subcollections, the embed() operator can be used to embed subcollections. The following will instruct the API to in-line the resourceRecords subcollection under the _embedded field of a Zone resource.

Request

GET http://{Address_Manager_IP}/api/v2/zones/100927/zones?fields=embed(resourceRecords)
Authorization: Basic {basicAuthenticationCredentials}

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "count": 1,
  "data": [
    {
      "id": 100928,
      "type": "Zone",
      "name": "bluecatlabs",
      "configuration": {
        "id": 100898,
        "type": "Configuration",
        "name": "config-1",
        "_links": {
          "self": {
            "href": "/api/v2/configurations/100898"
          }
        }
      },
      "absoluteName": "bluecatlabs.com",
      ...
      "_links": {
        "self": {
          "href": "/api/v2/zones/100928"
        },
        "collection": {
          "href": "/api/v2/zones/100927/zones"
        },
        "up": {
          "href": "/api/v2/zones/100927"
        },
        "resourceRecords": {
          "href": "/api/v2/zones/100928/resourceRecords"
        },
        "zones": {
          "href": "/api/v2/zones/100928/zones"
        },
        ...
      },
      "_embedded": {
        "resourceRecords": [
          {
            "id": 100933,
            "type": "HostRecord",
            "name": "bam",
            "configuration": {
              "id": 100898,
              "type": "Configuration",
              "name": "config-1",
              "_links": {
                "self": {
                  "href": "/api/v2/configurations/100898"
                }
              }
            },
            "absoluteName": "bam.bluecatlabs.com",
            ...
            "_links": {
              "self": {
                "href": "/api/v2/resourceRecords/100933"
              },
              "collection": {
                "href": "/api/v2/zones/100928/resourceRecords"
              },
              "up": {
                "href": "/api/v2/zones/100928"
              },
              "addresses": {
                "href": "/api/v2/resourceRecords/100933/addresses"
              },
              "dependentRecords": {
                "href": "/api/v2/resourceRecords/100933/dependentRecords"
              },
              ...
            },
            "_embedded": {}
          }
        ]
      }
    }
  ]
}

Specifying a field path will recursively embed subcollections. The following fetch will embed the resourceRecords subcollection and for each resource record embed their addresses subcollection:

Request

GET http://{Address_Manager_IP}/api/v2/zones/100927/zones?fields=embed(resourceRecords.addresses)
Authorization: Basic {basicAuthenticationCredentials}

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "count": 1,
  "data": [
    {
      "id": 100928,
      "type": "Zone",
      "name": "bluecatlabs",
      "configuration": {
        "id": 100898,
        "type": "Configuration",
        "name": "config-1",
        "_links": {
          "self": {
            "href": "/api/v2/configurations/100898"
          }
        }
      },
      "absoluteName": "bluecatlabs.com",
      ...
      "_links": {
        "self": {
          "href": "/api/v2/zones/100928"
        },
        "collection": {
          "href": "/api/v2/zones/100927/zones"
        },
        "up": {
          "href": "/api/v2/zones/100927"
        },
        "resourceRecords": {
          "href": "/api/v2/zones/100928/resourceRecords"
        },
        "zones": {
          "href": "/api/v2/zones/100928/zones"
        },
        ...
      },
      "_embedded": {
        "resourceRecords": [
          {
            "id": 100933,
            "type": "HostRecord",
            "name": "bam",
            "configuration": {
              "id": 100898,
              "type": "Configuration",
              "name": "config-1",
              "_links": {
                "self": {
                  "href": "/api/v2/configurations/100898"
                }
              }
            },
            "absoluteName": "bam.bluecatlabs.com",
            ...
            "_links": {
              "self": {
                "href": "/api/v2/resourceRecords/100933"
              },
              "collection": {
                "href": "/api/v2/zones/100928/resourceRecords"
              },
              "up": {
                "href": "/api/v2/zones/100928"
              },
              "addresses": {
                "href": "/api/v2/resourceRecords/100933/addresses"
              },
              "dependentRecords": {
                "href": "/api/v2/resourceRecords/100933/dependentRecords"
              },
              ...
            },
            "_embedded": {
              "addresses": [
                {
                  "id": 100932,
                  "type": "IPv4Address",
                  "name": null,
                  "configuration": {
                    "id": 100898,
                    "type": "Configuration",
                    "name": "config-1",
                    "_links": {
                      "self": {
                        "href": "/api/v2/configurations/100898"
                      }
                    }
                  },
                  "address": "192.168.1.15",
                  ...
                  "_links": {
                    "self": {
                      "href": "/api/v2/addresses/100932"
                    },
                    "collection": {
                      "href": "/api/v2/networks/100930/addresses"
                    },
                    "up": {
                      "href": "/api/v2/networks/100930"
                    },
                    "leases": {
                      "href": "/api/v2/addresses/100932/leases"
                    },
                    "resourceRecords": {
                      "href": "/api/v2/addresses/100932/resourceRecords"
                    },
                    ...
                  },
                  "_embedded": {}
                }
              ]
            }
          }
        ]
      }
    }
  ]
}