Retrieving Resources with Expansion

The resource expansion feature is used when the expand query parameter is included in the request. The response will include the additional fields of the expanded object contained in the resulting JSON document.

For example, the directlyConnectedOwner field has been expanded in the following query:

GET https://MySmartHome-MyCompany.iot.us1.oraclecloud.com/iot/api/endpoints/101?fields=type,id,description,directlyConnectedOwner&expand=directlyConnectedOwner

For brevity, only a few fields have been included in the resulting response example shown below.

{
    "items": [{
        "type": "IoTApplication",
        "id": 0-HA,
        "description": "Locking Control Application",
        "directlyConnectedOwner": {
            "type": "SmartDevice",
            "id": 0-MQ,
            "description": "Office Lock",
            "directlyConnectedOwner": {
                "links": [
                    { "rel": "canonical",
                      "href": http://.../iot/api/v1/endpoints/123"}
                 ]
            }
            "links": [
                    { "rel": "canonical",
                      "href": http://.../iot/api/v1/endpoints/123" },
                    { "rel": "self",
                      "href": http://.../iot/api/v1/endpoints/123"}
             ]
          }
        }],
        "links": [
           { "rel": "canonical",
             "href": http://.../iot/api/v1/endpoints/100" },
           { "rel": "self",
             "href": http://.../iot/api/endpoints/101?fields=type,id,description,directlyConnectedOwner&expands=directlyConnectedOwner" }
        ]
}

As can be seen in this example, expansion is only a single level deep. Expansion can be used for cases where the resource being queried has a single reference (or null reference) to another resource. You can also expand the results of a collection of resources by using the expandLinks query parameter. It works similarly to the expand query parameter.

The following request example:

GET https://MySmartHome-MyCompany.iot.us1.oraclecloud.com/iot/api/endpoints/101?fields=type,id,description,hostedArtifacts&expand=hostedArtifacts

will give the following result:

{
    "items": [{
        "type": "SmartDevice",
        "id": 0-MQ,
        "description": "Office Lock",
        "hostedArtifacts": {
            "items": [{
                "id": 1000,
                "lastModified": "2014-06-07T13:38:03.794Z",
                "startLevel": 2,
                "version": "1.0.3",
                "name": "com.somebody.bundle.a",
                "state": "ACTIVE",
                "links": [
                    {
                       "rel": "canonical",
                       "href": http://.../iot/api/v1/endpoints/123/artifacts/1000"},
                    {
                       "rel":"self",
                       "href": http://.../iot/api/v1/endpoints/123/artifacts/1000"}
                ]},
                { 
                "id": 1001,
                "lastModified": "2014-06-07T13:38:03.794Z",
                "startLevel": 2,
                "version": "3.1",
                "name": "com.somebody.bundle.b",
                "state": "INSTALLING",
                "links": [
                    {
                       "rel": "canonical",
                       "href": http://.../iot/api/v1/endpoints/123/artifacts/1001"},
                    {
                       "rel": "self",
                       "href": http://.../iot/api/v1/endpoints/123/artifacts/1001"}
                ]}, 
                {
                "id": 1002,
                "lastModified": "2014-06-07T13:38:03.794Z",
                "startLevel": 2,
                "version": "1.1",
                "name": "com.somebody.bundle.c",
                "state": "RESOLVED",
                "links": [
                   {
                       "rel": "canonical",
                       "href": http://.../iot/api/v1/endpoints/123/artifacts/1002"},
                   {
                       "rel": "self",
                       "href": http://.../iot/api/v1/endpoints/123/artifacts/1002"}
                ], 
                {
                "id": 3131,
                "lastModified": "2014-06-07T13:38:03.794Z",
                "startLevel": 2,
                "version": "0.0.4",
                "name": "com.somebody.bundle.d",
                "state": "ACTIVE",
                "links": [
                   {
                      "rel": "canonical",
                      "href": http://.../iot/api/v1/endpoints/123/artifacts/3131"},
                   {
                      "rel": "self",
                      "href": http://.../iot/api/v1/endpoints/123/artifacts/3131"}
                ]}
            ],
            "links": [
               {
                     "rel": "canonical", 
                     "href": http://.../iot/api/v1/endpoints"},
               {
                    "rel": "self", 
                    "href": http://.../iot/api/endpoints?fields=id,description"}
            ]
  }]
}